diff --git a/.github/workflows/build-and-upload.yml b/.github/workflows/build-and-upload.yml
index 2dd97162..b14af9da 100644
--- a/.github/workflows/build-and-upload.yml
+++ b/.github/workflows/build-and-upload.yml
@@ -317,15 +317,98 @@ jobs:
       - name: Verify bundled Node resource (Electron Linux)
         run: node scripts/verify-bundled-node.cjs packages/electron-app/electron/resources@linux-x64
 
+      - name: Verify Electron portable archive
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          archives=(packages/electron-app/release/*.tar.gz)
+          if [ "${#archives[@]}" -ne 1 ]; then
+            echo "Expected one Electron Linux tar.gz, found ${#archives[@]}" >&2
+            exit 1
+          fi
+
+          extract_dir=$(mktemp -d)
+          trap 'rm -rf "$extract_dir"' EXIT
+          tar -xzf "${archives[0]}" -C "$extract_dir"
+
+          binary=$(find "$extract_dir" -type f -name CodeNomad -print -quit)
+          if [ -z "$binary" ] || [ ! -x "$binary" ]; then
+            echo "Electron portable archive does not contain an executable CodeNomad binary" >&2
+            exit 1
+          fi
+
+          resources_dir="$(dirname "$binary")/resources"
+          node scripts/smoke-packaged-resources.cjs \
+            --resources "$resources_dir" \
+            --target linux-x64
+
+          app_asar="$resources_dir/app.asar"
+          if [ ! -f "$app_asar" ]; then
+            echo "Electron portable archive does not contain resources/app.asar" >&2
+            exit 1
+          fi
+          node - "$app_asar" <<'NODE'
+          const asar = require("@electron/asar")
+          const path = require("node:path")
+          const archive = process.argv[2]
+          const files = asar.listPackage(archive).map((file) =>
+            file.replace(/^[/\\]/, "").replaceAll("\\", "/"),
+          )
+          const fileSet = new Set(files)
+          const loadingPath = "dist/renderer/loading.html"
+          if (!fileSet.has(loadingPath)) {
+            throw new Error("Electron app.asar is missing dist/renderer/loading.html")
+          }
+          if (!files.some((file) => file.startsWith("dist/renderer/assets/") && !file.endsWith("/"))) {
+            throw new Error("Electron app.asar does not contain renderer assets")
+          }
+          const html = asar.extractFile(archive, loadingPath).toString("utf8")
+          for (const match of html.matchAll(/\b(?:src|href)=["']([^"']+)["']/g)) {
+            const reference = match[1]
+            if (/^(?:[a-z]+:|#)/i.test(reference)) continue
+            const cleanReference = reference.split(/[?#]/, 1)[0]
+            const target = cleanReference.startsWith("/")
+              ? cleanReference.slice(1)
+              : path.posix.normalize(path.posix.join(path.posix.dirname(loadingPath), cleanReference))
+            if (!fileSet.has(target)) {
+              throw new Error(`Electron app.asar is missing renderer reference ${target}`)
+            }
+          }
+          NODE
+
+          ldd "$binary" | tee /tmp/codenomad-electron-ldd.txt
+          if grep -q "not found" /tmp/codenomad-electron-ldd.txt; then
+            echo "Electron portable binary has unresolved shared libraries" >&2
+            exit 1
+          fi
+
       - name: Upload release assets
         if: ${{ inputs.upload && inputs.tag != '' }}
         run: |
           set -euo pipefail
           shopt -s nullglob
-          for file in packages/electron-app/release/*.zip packages/electron-app/release/*.AppImage; do
-            [ -f "$file" ] || continue
-            echo "Uploading $file"
-            gh release upload "$TAG" "$file" --clobber
+          files=(packages/electron-app/release/*.tar.gz)
+          if [ "${#files[@]}" -ne 1 ]; then
+            echo "Expected one Electron Linux release asset, found ${#files[@]}" >&2
+            exit 1
+          fi
+
+          file="${files[0]}"
+          asset_name=$(basename "$file")
+          echo "Uploading $file"
+          gh release upload "$TAG" "$file" --clobber
+          if ! gh release view "$TAG" --json assets --jq '.assets[].name' | grep -Fxq -- "$asset_name"; then
+            echo "Uploaded Electron Linux asset is missing from release: $asset_name" >&2
+            exit 1
+          fi
+
+          gh release view "$TAG" --json assets --jq '.assets[].name' | while IFS= read -r asset; do
+            case "$asset" in
+              CodeNomad-Electron-linux-*.zip|CodeNomad-Electron-linux-*.AppImage|CodeNomad-Electron-linux-*.flatpak)
+                echo "Deleting obsolete Linux asset $asset"
+                gh release delete-asset "$TAG" "$asset" --yes
+                ;;
+            esac
           done
 
       - name: Upload Actions artifacts (Electron Linux)
@@ -333,9 +416,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: ${{ inputs.actions_artifacts_name_prefix }}electron-linux
-          path: |
-            packages/electron-app/release/*.zip
-            packages/electron-app/release/*.AppImage
+          path: packages/electron-app/release/*.tar.gz
           retention-days: ${{ inputs.actions_artifacts_retention_days }}
           if-no-files-found: error
 
@@ -364,6 +445,9 @@ jobs:
         if: ${{ inputs.set_versions && inputs.version != '' }}
         run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
 
+      - name: Sync Tauri package version
+        run: npm run sync:version --workspace @codenomad/tauri-app
+
       - name: Install dependencies
         run: npm ci --workspaces --include=optional
 
@@ -451,6 +535,9 @@ jobs:
         if: ${{ inputs.set_versions && inputs.version != '' }}
         run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
 
+      - name: Sync Tauri package version
+        run: npm run sync:version --workspace @codenomad/tauri-app
+
       - name: Install dependencies
         run: npm ci --workspaces --include=optional
 
@@ -539,6 +626,9 @@ jobs:
         run: npm version ${{ env.VERSION }} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
         shell: bash
 
+      - name: Sync Tauri package version
+        run: npm run sync:version --workspace @codenomad/tauri-app
+
       - name: Install dependencies
         run: npm ci --workspaces --include=optional
 
@@ -643,6 +733,9 @@ jobs:
         if: ${{ inputs.set_versions && inputs.version != '' }}
         run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
 
+      - name: Sync Tauri package version
+        run: npm run sync:version --workspace @codenomad/tauri-app
+
       - name: Install dependencies
         run: npm ci --workspaces --include=optional
 
@@ -669,53 +762,135 @@ jobs:
           echo "Tauri CLI failed to load after retries" >&2
           exit 1
 
-      - name: Build Linux bundle (Tauri)
+      - name: Build Debian package (Tauri)
         working-directory: packages/tauri-app
-        run: npm exec -- tauri build
+        run: npm exec -- tauri build --bundles deb
 
-      - name: Package Tauri artifacts (Linux)
+      - name: Package and verify Tauri deb
         if: ${{ inputs.upload || inputs.upload_actions_artifacts }}
         run: |
           set -euo pipefail
-          SEARCH_ROOT="packages/tauri-app/target"
+          BUNDLE_ROOT="packages/tauri-app/target/release/bundle/deb"
           ARTIFACT_DIR="packages/tauri-app/release-tauri"
+          VERSION_TO_USE="${VERSION:-}"
+          if [ -z "$VERSION_TO_USE" ]; then
+            VERSION_TO_USE=$(node -p "require('./packages/tauri-app/package.json').version")
+          fi
           rm -rf "$ARTIFACT_DIR"
           mkdir -p "$ARTIFACT_DIR"
-          shopt -s nullglob globstar
+          shopt -s nullglob
 
-          find_one() {
-            find "$SEARCH_ROOT" -type f -iname "$1" | head -n1
-          }
-
-          appimage=$(find_one "*.AppImage")
-          fallback_bin="$SEARCH_ROOT/release/codenomad-tauri"
-
-          if [ -z "$appimage" ] || [ ! -f "$fallback_bin" ]; then
-            echo "Missing bundle(s): appimage=${appimage:-none} binary=$fallback_bin" >&2
+          debs=("$BUNDLE_ROOT"/*.deb)
+          if [ "${#debs[@]}" -ne 1 ]; then
+            echo "Expected one Tauri deb under $BUNDLE_ROOT, found ${#debs[@]}" >&2
             exit 1
           fi
 
-          cp "$appimage" "$ARTIFACT_DIR/CodeNomad-Tauri-linux-x64-${VERSION}.AppImage"
-          zip -j "$ARTIFACT_DIR/CodeNomad-Tauri-linux-x64-${VERSION}.zip" "$fallback_bin"
+          artifact="$ARTIFACT_DIR/CodeNomad-Tauri-linux-x64-${VERSION_TO_USE}.deb"
+          cp "${debs[0]}" "$artifact"
+          dpkg-deb --info "$artifact"
+          dpkg-deb --contents "$artifact"
+          package_version=$(dpkg-deb --field "$artifact" Version)
+          if [ "$package_version" != "$VERSION_TO_USE" ]; then
+            echo "Tauri deb version mismatch: expected $VERSION_TO_USE, found $package_version" >&2
+            exit 1
+          fi
+
+          extract_dir=$(mktemp -d)
+          trap 'rm -rf "$extract_dir"' EXIT
+          dpkg-deb --extract "$artifact" "$extract_dir"
+
+          binary="$extract_dir/usr/bin/codenomad-tauri"
+          resources_dir="$extract_dir/usr/lib/CodeNomad/resources"
+          desktop_file="$extract_dir/usr/share/applications/CodeNomad.desktop"
+          for required in "$binary" "$resources_dir" "$desktop_file"; do
+            if [ ! -e "$required" ]; then
+              echo "Missing path in Tauri deb: $required" >&2
+              exit 1
+            fi
+          done
+
+          grep -Fx "Exec=codenomad-tauri" "$desktop_file"
+          if grep -Fxq "NoDisplay=true" "$desktop_file"; then
+            echo "Generated Tauri desktop entry must be visible" >&2
+            exit 1
+          fi
+          node scripts/smoke-packaged-resources.cjs \
+            --resources "$resources_dir" \
+            --loading "$resources_dir/ui-loading" \
+            --target linux-x64
+
+          ldd "$binary" | tee /tmp/codenomad-tauri-ldd.txt
+          if grep -q "not found" /tmp/codenomad-tauri-ldd.txt; then
+            echo "Tauri deb binary has unresolved shared libraries" >&2
+            exit 1
+          fi
+
+      - name: Verify Tauri deb installation on Ubuntu 24.04
+        if: ${{ inputs.upload || inputs.upload_actions_artifacts }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          debs=(packages/tauri-app/release-tauri/*.deb)
+          if [ "${#debs[@]}" -ne 1 ]; then
+            echo "Expected one packaged Tauri deb, found ${#debs[@]}" >&2
+            exit 1
+          fi
+
+          artifact=$(realpath "${debs[0]}")
+          docker run --rm \
+            --volume "$artifact:/tmp/codenomad.deb:ro" \
+            ubuntu:24.04 \
+            bash -euc '
+              export DEBIAN_FRONTEND=noninteractive
+              apt-get update >/dev/null
+              apt-get install -y /tmp/codenomad.deb >/dev/null
+              test -x /usr/bin/codenomad-tauri
+              test -x /usr/lib/CodeNomad/resources/node/linux-x64/bin/node
+              test -f /usr/lib/CodeNomad/resources/server/dist/bin.js
+              test -f /usr/lib/CodeNomad/resources/ui-loading/loading.html
+              /usr/lib/CodeNomad/resources/node/linux-x64/bin/node \
+                /usr/lib/CodeNomad/resources/server/dist/bin.js --version
+              ldd /usr/bin/codenomad-tauri | tee /tmp/codenomad-tauri-ldd.txt
+              ! grep -q "not found" /tmp/codenomad-tauri-ldd.txt
+            '
 
       - name: Upload Actions artifacts (Tauri Linux)
         if: ${{ inputs.upload_actions_artifacts }}
         uses: actions/upload-artifact@v4
         with:
           name: ${{ inputs.actions_artifacts_name_prefix }}tauri-linux
-          path: packages/tauri-app/release-tauri/*
+          path: packages/tauri-app/release-tauri/*.deb
           retention-days: ${{ inputs.actions_artifacts_retention_days }}
-          if-no-files-found: warn
+          if-no-files-found: error
 
       - name: Upload Tauri release assets (Linux)
         if: ${{ inputs.upload && inputs.tag != '' }}
         run: |
           set -euo pipefail
           shopt -s nullglob
-          for file in packages/tauri-app/release-tauri/*; do
-            [ -f "$file" ] || continue
-            echo "Uploading $file"
-            gh release upload "$TAG" "$file" --clobber
+          files=(packages/tauri-app/release-tauri/*.deb)
+          if [ "${#files[@]}" -ne 1 ]; then
+            echo "Expected one Tauri Linux release asset, found ${#files[@]}" >&2
+            exit 1
+          fi
+
+          file="${files[0]}"
+          asset_name=$(basename "$file")
+          echo "Uploading $file"
+          gh release upload "$TAG" "$file" --clobber
+          if ! gh release view "$TAG" --json assets --jq '.assets[].name' | grep -Fxq -- "$asset_name"; then
+            echo "Uploaded Tauri Linux asset is missing from release: $asset_name" >&2
+            exit 1
+          fi
+
+          gh release view "$TAG" --json assets --jq '.assets[].name' | while IFS= read -r asset; do
+            case "$asset" in
+              CodeNomad-Tauri-linux-*.zip|CodeNomad-Tauri-linux-*.AppImage|CodeNomad-Tauri-linux-*.rpm|CodeNomad-Tauri-linux-*.flatpak)
+                echo "Deleting obsolete Linux asset $asset"
+                gh release delete-asset "$TAG" "$asset" --yes
+                ;;
+            esac
           done
 
   build-tauri-linux-arm64:
@@ -772,6 +947,9 @@ jobs:
       - name: Set workspace versions
         run: npm version ${VERSION} --workspaces --include-workspace-root --no-git-tag-version --allow-same-version
 
+      - name: Sync Tauri package version
+        run: npm run sync:version --workspace @codenomad/tauri-app
+
       - name: Install dependencies
         run: npm ci --workspaces --include=optional
 
diff --git a/.github/workflows/comment-pr-artifacts.yml b/.github/workflows/comment-pr-artifacts.yml
index 1b308d62..e6383bcf 100644
--- a/.github/workflows/comment-pr-artifacts.yml
+++ b/.github/workflows/comment-pr-artifacts.yml
@@ -93,6 +93,11 @@ jobs:
               return;
             }
 
+            if (matchedRun.conclusion !== 'success') {
+              core.setFailed(`PR Build Validation run ${matchedRun.id} concluded ${matchedRun.conclusion}.`);
+              return;
+            }
+
             const artifacts = await github.paginate(
               github.rest.actions.listWorkflowRunArtifacts,
               { owner, repo, run_id: matchedRun.id, per_page: 100 }
diff --git a/.github/workflows/pr-build.yml b/.github/workflows/pr-build.yml
index cf8a11a2..9ab747b1 100644
--- a/.github/workflows/pr-build.yml
+++ b/.github/workflows/pr-build.yml
@@ -46,7 +46,10 @@ jobs:
           fi
 
   build:
-    needs: authorize
+    needs:
+      - authorize
+      - tests
+      - tests-tauri-windows
     if: ${{ needs.authorize.outputs.allowed == 'true' && !github.event.pull_request.draft }}
     uses: ./.github/workflows/build-and-upload.yml
     with:
@@ -56,3 +59,119 @@ jobs:
       actions_artifacts_retention_days: 7
       actions_artifacts_name_prefix: pr-${{ github.event.pull_request.number }}-${{ github.event.pull_request.head.sha }}-
       set_versions: false
+
+  tests:
+    needs: authorize
+    if: ${{ needs.authorize.outputs.allowed == 'true' && !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install Linux test dependencies (Tauri)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            pkg-config \
+            libgtk-3-dev \
+            libglib2.0-dev \
+            libwebkit2gtk-4.1-dev \
+            libsoup-3.0-dev \
+            libayatana-appindicator3-dev \
+            librsvg2-dev
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck desktop clients
+        run: npm run typecheck
+
+      - name: Test Electron client state
+        run: npm run test:native --workspace @neuralnomads/codenomad-electron-app
+
+      - name: Test changed runnable UI behavior
+        run: >-
+          node --import tsx --test
+          packages/ui/src/components/session-list-visibility.test.ts
+          packages/ui/src/lib/hooks/use-app-session-capture.test.ts
+          packages/ui/src/lib/message-selection-position.test.ts
+          packages/ui/src/lib/trailing-resync.test.ts
+          packages/ui/src/stores/abort-created-workspace-cleanup.test.ts
+          packages/ui/src/stores/app-session-reconciliation.test.ts
+          packages/ui/src/stores/app-session-restore-gate.test.ts
+          packages/ui/src/stores/app-session-restore-queue.test.ts
+          packages/ui/src/stores/app-session-restore-timeout.test.ts
+          packages/ui/src/stores/app-session-snapshot-merge.test.ts
+          packages/ui/src/stores/restore-workspace-commit-gates.test.ts
+          packages/ui/src/stores/client-state-codec.test.ts
+          packages/ui/src/stores/client-state.test.ts
+          packages/ui/src/stores/instances-restore-cancellation.test.ts
+          packages/ui/src/stores/message-v2/message-hydration-authority.test.ts
+          packages/ui/src/stores/session-generation-recovery.test.ts
+          packages/ui/src/stores/session-metadata.test.ts
+          packages/ui/src/stores/session-pagination.test.ts
+          packages/ui/src/stores/workspace-list-reconciliation-fence.test.ts
+
+      - name: Test restore ownership integration
+        run: >-
+          node --conditions=browser --import tsx --test --test-force-exit
+          packages/ui/src/stores/instances-restore-ownership.test.ts
+          packages/ui/src/stores/permission-lifecycle.test.ts
+
+      - name: Test server
+        run: node --import tsx --test "packages/server/src/**/*.test.ts"
+
+      - name: Prepare Tauri test resources
+        run: >-
+          npm run dev:prep --workspace @codenomad/tauri-app &&
+          node -e "require('fs').mkdirSync('packages/tauri-app/src-tauri/resources/server',{recursive:true})"
+
+      - name: Test Tauri crate
+        working-directory: packages/tauri-app/src-tauri
+        run: cargo test --locked
+
+  tests-tauri-windows:
+    needs: authorize
+    if: ${{ needs.authorize.outputs.allowed == 'true' && !github.event.pull_request.draft }}
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Test Windows server spawn behavior
+        run: node --import tsx --test packages/server/src/workspaces/__tests__/spawn.test.ts
+
+      - name: Prepare Tauri test resources
+        run: >-
+          npm run dev:prep --workspace @codenomad/tauri-app &&
+          node -e "require('fs').mkdirSync('packages/tauri-app/src-tauri/resources/server',{recursive:true})"
+
+      - name: Test Tauri crate on Windows
+        working-directory: packages/tauri-app/src-tauri
+        run: cargo test --locked
diff --git a/.opencode/skills/codenomad-architecture-guide/references/feature-traces.md b/.opencode/skills/codenomad-architecture-guide/references/feature-traces.md
index 286d32d8..2aa5a42d 100644
--- a/.opencode/skills/codenomad-architecture-guide/references/feature-traces.md
+++ b/.opencode/skills/codenomad-architecture-guide/references/feature-traces.md
@@ -7,11 +7,12 @@ End-to-end feature flows with decision branches and mechanism references.
 1. **Server:** Backend emits SSE event `permission.asked` or `permission.updated`
    - Events are pushed through the instance event stream
 
-2. **UI Store:** `packages/ui/src/stores/instances.ts` receives via `serverEvents` handler
-   - **Branch:** IF `isPermissionAutoAcceptEnabled(instanceId, sessionId)` is true
-     - **Mechanism:** `drainAutoAcceptPermissions()` in `packages/ui/src/stores/permission-auto-accept.ts`
-     - **Action:** Automatically calls `Permission.reply()`, skips modal display
-     - **File:** `packages/ui/src/stores/permission-auto-accept.ts:drainAutoAcceptPermission()`
+2. **Server AutoAcceptManager** intercepts permission events (if Yolo is enabled)
+   - **File:** `packages/server/src/permissions/auto-accept-manager.ts`
+   - **Action:** Auto-replies via SDK client, emits `yolo.autoAccepted` to UI for immediate queue cleanup
+   - **Pending drain:** Re-drains pending permissions on toggle(enable) and session ancestry changes
+3. **UI Store:** `packages/ui/src/stores/instances.ts` receives via `serverEvents`
+   - **Branch:** IF `yolo.autoAccepted` event arrives → marks replied + removes from queue immediately
    - **Branch:** ELSE (normal flow)
      - **Mechanism:** Permission queued in `permissionQueues` signal
      - **Action:** Display approval modal
diff --git a/.opencode/skills/codenomad-architecture-guide/references/sdk-integration-patterns.md b/.opencode/skills/codenomad-architecture-guide/references/sdk-integration-patterns.md
index eda86515..3f5d4321 100644
--- a/.opencode/skills/codenomad-architecture-guide/references/sdk-integration-patterns.md
+++ b/.opencode/skills/codenomad-architecture-guide/references/sdk-integration-patterns.md
@@ -129,20 +129,20 @@ Rapid successive operations can cause temporary desync:
 
 1. **Server emits** `permission.asked` or `permission.updated` SSE event
    - Pushed through instance event stream
-2. **UI Store receives** via `serverEvents`
+2. **Server AutoAcceptManager** intercepts the event (if Yolo is enabled)
+   - File: `packages/server/src/permissions/auto-accept-manager.ts`
+   - Action: Auto-replies via SDK client (`createInstanceClient`), tracks pending permissions, drains on enable/ancestry change
+   - Emits `yolo.autoAccepted` + `yolo.stateChanged` events to UI
+3. **UI Store receives** via `serverEvents`
    - File: `packages/ui/src/stores/instances.ts`
-   - **Branch:** IF `isPermissionAutoAcceptEnabled()` 
-     - Mechanism: `drainAutoAcceptPermissions()` in `packages/ui/src/stores/permission-auto-accept.ts`
-     - Action: Calls reply immediately, skips modal
-   - **Branch:** ELSE 
-     - Mechanism: Queued in `permissionQueues`
-     - Action: Display modal
-3. **UI Store:** `packages/ui/src/stores/message-v2/bridge.ts` calls `upsertPermissionV2()`
-4. **UI Component:** `packages/ui/src/components/permission-approval-modal.tsx` displays
-5. **User Action:** Calls `packages/ui/src/stores/instances.ts:sendPermissionResponse()`
-6. **SDK Call:** `client.permission.reply()` via `packages/ui/src/lib/opencode-api.ts`
-7. **Optimistic Update:** `removePermissionV2()` in bridge
-8. **SSE Confirmation:** `permission.replied` event
+   - **Branch:** IF `yolo.autoAccepted` event arrives → immediately marks replied + removes from queue
+   - **Branch:** ELSE (user must reply) → Queued in `permissionQueues` → Display modal
+4. **UI Store:** `packages/ui/src/stores/message-v2/bridge.ts` calls `upsertPermissionV2()`
+5. **UI Component:** `packages/ui/src/components/permission-approval-modal.tsx` displays
+6. **User Action:** Calls `packages/ui/src/stores/instances.ts:sendPermissionResponse()`
+7. **SDK Call:** `client.permission.reply()` via `packages/ui/src/lib/opencode-api.ts`
+8. **Optimistic Update:** `removePermissionV2()` in bridge
+9. **SSE Confirmation:** `permission.replied` event
    - **Branch:** IF SSE disconnected → `syncPendingPermissions()` reconciles on reconnect
 
 ## Session Event Handling
diff --git a/BUILD.md b/BUILD.md
index 0ae1909f..60c2415a 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -56,14 +56,14 @@ bun run build:win-arm64
 ### Linux
 
 ```bash
-# x64 (64-bit)
-bun run build:linux
+# Portable Electron archive (x64)
+npm run build:linux --workspace @neuralnomads/codenomad-electron-app
 
-# ARM64
-bun run build:linux-arm64
+# Tauri Debian package (x64)
+npm exec --workspace @codenomad/tauri-app -- tauri build --bundles deb
 ```
 
-**Output formats:** `.AppImage`, `.deb`, `.tar.gz`
+**Release formats:** Electron `.tar.gz` portable archive and Tauri `.deb` installer.
 
 ### Build All Platforms
 
@@ -83,27 +83,29 @@ The build script performs these steps:
 
 ## Output
 
-Binaries are generated in the `release/` directory:
+Build artifacts are generated in package-specific output directories:
 
 ```
-release/
-├── CodeNomad-0.1.0-mac-universal.dmg
-├── CodeNomad-0.1.0-mac-universal.zip
-├── CodeNomad-0.1.0-win-x64.exe
-├── CodeNomad-0.1.0-linux-x64.AppImage
-└── ...
+packages/electron-app/release/
+└── CodeNomad-Electron-linux-x64-0.18.0.tar.gz
+
+packages/tauri-app/target/release/bundle/deb/
+└── CodeNomad_0.18.0_amd64.deb
 ```
 
 ## File Naming Convention
 
 ```
-CodeNomad-{version}-{os}-{arch}.{ext}
+CodeNomad-Electron-{os}-{arch}-{version}.{ext}
+CodeNomad-Tauri-{os}-{arch}-{version}.{ext}
 ```
 
-- **version**: From package.json (e.g., `0.1.0`)
-- **os**: `mac`, `win`, `linux`
+- **version**: From package.json (e.g., `0.18.0`)
+- **os**: `macos`, `windows`, `linux`
 - **arch**: `x64`, `arm64`, `universal`
-- **ext**: `dmg`, `zip`, `exe`, `AppImage`, `deb`, `tar.gz`
+- **ext**: `dmg`, `zip`, `exe`, `deb`, `tar.gz`
+
+The Tauri build directory uses Tauri's native Debian filename. CI renames the package to the convention above when preparing release assets.
 
 ## Platform Requirements
 
@@ -121,9 +123,9 @@ CodeNomad-{version}-{os}-{arch}.{ext}
 
 ### Linux
 
-- **Build on:** Any platform
-- **Run on:** Ubuntu 18.04+, Debian 10+, Fedora 32+, Arch
-- **Dependencies:** Varies by distro
+- **Build on:** Linux x64
+- **Electron portable:** extract the tar.gz and run the `CodeNomad` executable
+- **Tauri deb:** built and installation-tested on Ubuntu 24.04; older distributions are not yet guaranteed
 
 ## Troubleshooting
 
@@ -136,13 +138,7 @@ xcode-select --install
 
 ### Build fails on Linux
 
-```bash
-# Install dependencies (Debian/Ubuntu)
-sudo apt-get install -y rpm
-
-# Install dependencies (Fedora)
-sudo dnf install -y rpm-build
-```
+Install the Electron and Tauri build dependencies documented by their upstream projects. Release builds currently target Linux x64 and produce an Electron portable archive plus a Tauri Debian package.
 
 ### "electron-builder not found"
 
diff --git a/README.md b/README.md
index 8da35441..946ce8cc 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,9 @@ Download the latest installer for your platform from [Releases](https://github.c
 |----------|---------|
 | macOS | DMG, ZIP (Universal: Intel + Apple Silicon) |
 | Windows | NSIS Installer, ZIP (x64, ARM64) |
-| Linux | AppImage, deb, tar.gz (x64, ARM64) |
+| Linux | Tauri deb, Electron portable tar.gz (x64) |
+
+The Tauri deb is currently built and installation-tested on Ubuntu 24.04. Compatibility with older Debian-based distributions is not yet guaranteed.
 
 ### 💻 CodeNomad Server
 
@@ -169,7 +171,7 @@ On Intel Macs, also check **System Settings → Privacy & Security** on first la
 WebKitGTK DMA-BUF/GBM issue. Run with:
 
 ```bash
-WEBKIT_DISABLE_DMABUF_RENDERER=1 codenomad
+WEBKIT_DISABLE_DMABUF_RENDERER=1 codenomad-tauri
 ```
 
 See full workaround in the original README.
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
new file mode 100644
index 00000000..9043845f
--- /dev/null
+++ b/THIRD_PARTY_NOTICES.md
@@ -0,0 +1,28 @@
+# Third-Party Notices
+
+## OpenChamber
+
+The provider usage adapters are derived from OpenChamber:
+https://github.com/openchamber/openchamber
+
+MIT License
+
+Copyright (c) 2025 Bohdan Triapitsyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/dev-docs/technical-implementation.md b/dev-docs/technical-implementation.md
index 5d7e6d68..bbfc6443 100644
--- a/dev-docs/technical-implementation.md
+++ b/dev-docs/technical-implementation.md
@@ -584,7 +584,7 @@ npm run package      # Create distributable
 
 - macOS: DMG + auto-update
 - Windows: NSIS installer + auto-update
-- Linux: AppImage + deb/rpm
+- Linux: Electron portable tar.gz + Tauri deb
 
 ## Configuration Files
 
diff --git a/docs/superpowers/specs/2026-07-14-bracket-math-delimiters-design.md b/docs/superpowers/specs/2026-07-14-bracket-math-delimiters-design.md
new file mode 100644
index 00000000..7a92b5bc
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-14-bracket-math-delimiters-design.md
@@ -0,0 +1,38 @@
+# Bracket Math Delimiters Design
+
+## Goal
+
+Support inline `\(...\)` and display `\[...\]` math in CodeNomad Markdown while preserving existing `$...$` and `$$...$$` behavior. No unrelated Markdown changes.
+
+## Approach
+
+Keep `marked-katex-extension` as owner of dollar-delimited math. Add two small parser-native Marked extensions in `packages/ui/src/lib/markdown.ts`:
+
+- Inline rule: recognize `\(...\)` and render with KaTeX `displayMode: false`.
+- Block rule: recognize `\[...\]` and render with KaTeX `displayMode: true`.
+
+Both rules will use `katex.renderToString()` with the same error policy as the existing integration: `throwOnError: false` and `strict: "ignore"`. Parser-native rules avoid source rewriting, ignore fenced/code content through Marked's normal lexer flow, and preserve unmatched delimiters as plain Markdown text.
+
+## Integration
+
+Register the two rules beside the existing `markedKatex(...)` registration in `setupRenderer()`. Existing renderer setup, syntax highlighting, HTML handling, styles, and component APIs remain unchanged. No new runtime dependency is needed because KaTeX is already a direct UI dependency.
+
+## Edge Cases
+
+- `\\(` and `\\[` remain escaped literal text rather than opening math.
+- Inline math must close with `\)` before a line break.
+- Display math may span lines and must close with `\]`.
+- Empty or unmatched delimiter pairs remain text.
+- Existing dollar delimiter boundary behavior remains controlled by `marked-katex-extension` with `nonStandard: true`.
+
+## Tests
+
+Add focused Markdown rendering regression tests covering:
+
+- `\(x^2\)` renders inline KaTeX.
+- `\[x^2\]` renders display KaTeX, including multiline content.
+- `$x^2$` and `$$x^2$$` still render.
+- Delimiters inside inline and fenced code remain literal.
+- Escaped, empty, and unmatched bracket delimiters remain literal.
+
+Run the repository's confirmed UI test command, UI typecheck, and inspect the final diff.
diff --git a/package-lock.json b/package-lock.json
index 5d08c142..473c9074 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -73,6 +73,7 @@
       "version": "7.28.5",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.27.1",
         "@babel/generator": "^7.28.5",
@@ -4295,6 +4296,7 @@
       "version": "7.20.5",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/parser": "^7.20.7",
         "@babel/types": "^7.20.7",
@@ -4396,6 +4398,7 @@
       "version": "22.19.0",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -4470,6 +4473,7 @@
       "integrity": "sha512-MCbrb508JZHqe7bUibmZj/lyojdhLRnfkmyXnkrCM2zVrjTgL89U8UEfInpKTvPeTnxsw2hmyZxnhsdNR6yhwg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "cac": "^6.7.14",
         "colorette": "^2.0.20",
@@ -4552,6 +4556,7 @@
       "version": "6.12.6",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.1",
         "fast-json-stable-stringify": "^2.0.0",
@@ -4754,7 +4759,6 @@
       "version": "5.3.2",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "archiver-utils": "^2.1.0",
         "async": "^3.2.4",
@@ -4772,7 +4776,6 @@
       "version": "2.1.0",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "glob": "^7.1.4",
         "graceful-fs": "^4.2.0",
@@ -4793,7 +4796,6 @@
       "version": "2.3.8",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "core-util-is": "~1.0.0",
         "inherits": "~2.0.3",
@@ -4807,14 +4809,12 @@
     "node_modules/archiver-utils/node_modules/safe-buffer": {
       "version": "5.1.2",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/archiver-utils/node_modules/string_decoder": {
       "version": "1.1.1",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "safe-buffer": "~5.1.0"
       }
@@ -5128,7 +5128,6 @@
       "version": "4.1.0",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "buffer": "^5.5.0",
         "inherits": "^2.0.4",
@@ -5192,6 +5191,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.9.0",
         "caniuse-lite": "^1.0.30001759",
@@ -5682,7 +5682,6 @@
       "version": "4.1.2",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "buffer-crc32": "^0.2.13",
         "crc32-stream": "^4.0.2",
@@ -5812,7 +5811,6 @@
       "version": "1.2.2",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "crc32": "bin/crc32.njs"
       },
@@ -5824,7 +5822,6 @@
       "version": "4.0.3",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "crc-32": "^1.2.0",
         "readable-stream": "^3.4.0"
@@ -6190,6 +6187,7 @@
       "version": "24.13.3",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "app-builder-lib": "24.13.3",
         "builder-util": "24.13.1",
@@ -6356,7 +6354,6 @@
       "version": "24.13.3",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "app-builder-lib": "24.13.3",
         "archiver": "^5.3.1",
@@ -6368,7 +6365,6 @@
       "version": "10.1.0",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "graceful-fs": "^4.2.0",
         "jsonfile": "^6.0.1",
@@ -6382,7 +6378,6 @@
       "version": "6.2.0",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "universalify": "^2.0.0"
       },
@@ -6394,7 +6389,6 @@
       "version": "2.0.1",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">= 10.0.0"
       }
@@ -7129,8 +7123,7 @@
     "node_modules/fs-constants": {
       "version": "1.0.0",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/fs-extra": {
       "version": "8.1.0",
@@ -8347,8 +8340,7 @@
     "node_modules/isarray": {
       "version": "1.0.0",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/isbinaryfile": {
       "version": "5.0.6",
@@ -8398,6 +8390,7 @@
       "version": "1.21.7",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "jiti": "bin/jiti.js"
       }
@@ -8554,7 +8547,6 @@
       "version": "1.0.1",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "readable-stream": "^2.0.5"
       },
@@ -8566,7 +8558,6 @@
       "version": "2.3.8",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "core-util-is": "~1.0.0",
         "inherits": "~2.0.3",
@@ -8580,14 +8571,12 @@
     "node_modules/lazystream/node_modules/safe-buffer": {
       "version": "5.1.2",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/lazystream/node_modules/string_decoder": {
       "version": "1.1.1",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "safe-buffer": "~5.1.0"
       }
@@ -8652,26 +8641,22 @@
     "node_modules/lodash.defaults": {
       "version": "4.2.0",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/lodash.difference": {
       "version": "4.5.0",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/lodash.flatten": {
       "version": "4.4.0",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/lodash.isplainobject": {
       "version": "4.0.6",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/lodash.sortby": {
       "version": "4.7.0",
@@ -8683,8 +8668,7 @@
     "node_modules/lodash.union": {
       "version": "4.6.0",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/lowercase-keys": {
       "version": "2.0.0",
@@ -8738,6 +8722,7 @@
     "node_modules/marked": {
       "version": "12.0.2",
       "license": "MIT",
+      "peer": true,
       "bin": {
         "marked": "bin/marked.js"
       },
@@ -9498,6 +9483,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.11",
         "picocolors": "^1.1.1",
@@ -9645,8 +9631,7 @@
     "node_modules/process-nextick-args": {
       "version": "2.0.1",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/process-warning": {
       "version": "3.0.0",
@@ -9895,7 +9880,6 @@
       "version": "3.6.2",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "inherits": "^2.0.3",
         "string_decoder": "^1.1.1",
@@ -9909,7 +9893,6 @@
       "version": "1.1.3",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "minimatch": "^5.1.0"
       }
@@ -10212,6 +10195,7 @@
       "version": "4.52.5",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@types/estree": "1.0.8"
       },
@@ -10435,6 +10419,7 @@
     "node_modules/seroval": {
       "version": "1.3.2",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=10"
       }
@@ -10758,6 +10743,7 @@
     "node_modules/solid-js": {
       "version": "1.9.10",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "csstype": "^3.1.0",
         "seroval": "~1.3.0",
@@ -10898,7 +10884,6 @@
       "version": "1.3.0",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "safe-buffer": "~5.2.0"
       }
@@ -11232,7 +11217,6 @@
       "version": "2.2.0",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "bl": "^4.0.3",
         "end-of-stream": "^1.4.1",
@@ -11425,6 +11409,7 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -11674,6 +11659,7 @@
       "version": "5.9.3",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -12021,6 +12007,7 @@
       "version": "5.4.21",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",
@@ -12879,6 +12866,7 @@
       "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "fast-deep-equal": "^3.1.3",
         "fast-uri": "^3.0.1",
@@ -13073,6 +13061,7 @@
       "integrity": "sha512-fS6iqSPZDs3dr/y7Od6y5nha8dW1YnbgtsyotCVvoFGKbERG++CVRFv1meyGDE1SNItQA8BrnCw7ScdAhRJ3XQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "rollup": "dist/bin/rollup"
       },
@@ -13361,7 +13350,6 @@
       "version": "4.1.1",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "archiver-utils": "^3.0.4",
         "compress-commons": "^4.1.2",
@@ -13375,7 +13363,6 @@
       "version": "3.0.4",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "glob": "^7.2.3",
         "graceful-fs": "^4.2.0",
@@ -13395,6 +13382,7 @@
     "node_modules/zod": {
       "version": "3.25.76",
       "license": "MIT",
+      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }
@@ -13454,6 +13442,7 @@
         "@fastify/cors": "^8.5.0",
         "@fastify/reply-from": "^9.8.0",
         "@fastify/static": "^7.0.4",
+        "@opencode-ai/sdk": "^1.17.8",
         "commander": "^12.1.0",
         "fastify": "^4.28.1",
         "fuzzysort": "^2.0.4",
diff --git a/packages/cloudflare/release-config.json b/packages/cloudflare/release-config.json
index bb49f85b..50efd5fa 100644
--- a/packages/cloudflare/release-config.json
+++ b/packages/cloudflare/release-config.json
@@ -1,4 +1,4 @@
 {
-  "minServerVersion": "0.17.0",
+  "minServerVersion": "0.18.0",
   "latestServerUrl": "https://github.com/NeuralNomadsAI/CodeNomad/releases/latest"
 }
diff --git a/packages/electron-app/electron/main/client-state-cross-host-child.ts b/packages/electron-app/electron/main/client-state-cross-host-child.ts
new file mode 100644
index 00000000..079032bb
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-cross-host-child.ts
@@ -0,0 +1,47 @@
+import { existsSync, writeFileSync } from "node:fs"
+import { CrossHostRegistration, createCrossHostOwner } from "./client-state-cross-host"
+import { getProcessStartIdentity } from "./client-state-process-identity"
+import { isPidAlive } from "./client-state-process"
+import { ClientStateManager } from "./client-state"
+
+const [directory, startPath, readyPath, mode, userDataPath, participantReadyPath, participantContinuePath, legacyTauriDataPath, operation, payload] = process.argv.slice(2)
+if (!directory || !startPath) throw new Error("Expected election directory and start path")
+if (readyPath) writeFileSync(readyPath, "")
+while (!existsSync(startPath)) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5)
+
+const manager = mode === "full" && userDataPath
+  ? new ClientStateManager(userDataPath, undefined, {
+      crossHostElectionDirectory: directory,
+      legacyTauriDataPath: legacyTauriDataPath || null,
+      crossHostDependencies: {
+        pidAlive: isPidAlive,
+        processStartIdentity: getProcessStartIdentity,
+        onParticipantPublished: participantReadyPath && participantContinuePath
+          ? () => {
+              writeFileSync(participantReadyPath, "")
+              while (!existsSync(participantContinuePath)) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5)
+            }
+          : undefined,
+      },
+    })
+  : undefined
+const owner = manager ? undefined : createCrossHostOwner()
+const registration = owner && CrossHostRegistration.register(directory, owner, true, {
+  pidAlive: mode === "retire-crash" ? () => false : isPidAlive,
+  processStartIdentity: getProcessStartIdentity,
+  onOwnerPrepared: mode === "owner-crash" ? () => process.exit(91) : undefined,
+  onOwnerRetired: mode === "retire-crash" ? () => process.exit(91) : undefined,
+})
+if (manager?.isPrimary && operation === "save") {
+  await manager.setRestoreEnabled(true)
+  await manager.saveClientState(JSON.parse(payload))
+}
+process.stdout.write(`${JSON.stringify({
+  acquired: manager?.isPrimary ?? Boolean(registration?.isPrimary),
+  state: operation === "load" ? manager?.loadClientState() : undefined,
+})}\n`)
+process.stdin.resume()
+process.stdin.once("end", () => {
+  if (manager) void manager.drainAndReleasePrimary().finally(() => process.exit())
+  else registration?.release()
+})
diff --git a/packages/electron-app/electron/main/client-state-cross-host.test.ts b/packages/electron-app/electron/main/client-state-cross-host.test.ts
new file mode 100644
index 00000000..1d7e0b38
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-cross-host.test.ts
@@ -0,0 +1,226 @@
+import assert from "node:assert/strict"
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"
+import { once } from "node:events"
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join, posix, win32 } from "node:path"
+import { fileURLToPath } from "node:url"
+import test from "node:test"
+import {
+  CrossHostRegistration,
+  CROSS_HOST_OWNER_DIRECTORY,
+  resolveCrossHostElectionDirectory,
+  resolveCrossHostStatePath,
+  type CrossHostLeaseDependencies,
+} from "./client-state-cross-host"
+import type { ProcessOwner } from "./client-state-process"
+
+function temp(t: test.TestContext): string {
+  const path = mkdtempSync(join(tmpdir(), "codenomad-cross-host-"))
+  t.after(() => rmSync(path, { recursive: true, force: true }))
+  return path
+}
+
+function owner(pid: number, token: string, identity = `${token}-start`): ProcessOwner {
+  return { pid, runToken: token, processStartIdentity: identity }
+}
+
+function dependencies(alive: boolean, identity?: string): CrossHostLeaseDependencies {
+  return { pidAlive: () => alive, processStartIdentity: () => identity }
+}
+
+function ownerFile(directory: string): string {
+  return join(directory, CROSS_HOST_OWNER_DIRECTORY, "owner.json")
+}
+
+interface Child {
+  process: ChildProcessWithoutNullStreams
+  result: Promise<boolean>
+}
+
+function child(directory: string, start: string, mode = ""): Child {
+  const process = spawn(globalThis.process.execPath, [
+    "--import", "tsx", fileURLToPath(new URL("./client-state-cross-host-child.ts", import.meta.url)), directory, start, "", mode,
+  ]) as ChildProcessWithoutNullStreams
+  process.stdout.setEncoding("utf8"); process.stderr.setEncoding("utf8")
+  const result = new Promise<boolean>((resolve, reject) => {
+    let output = "", errors = ""
+    process.stdout.on("data", (chunk: string) => {
+      output += chunk
+      if (output.includes("\n")) resolve(JSON.parse(output).acquired)
+    })
+    process.stderr.on("data", (chunk: string) => { errors += chunk })
+    process.once("error", reject)
+    process.once("exit", (code) => { if (!output && code !== 91) reject(new Error(`child ${code}: ${errors}`)) })
+  })
+  return { process, result }
+}
+
+async function stop(...children: Child[]): Promise<void> {
+  const running = children.filter(({ process }) => process.exitCode === null && process.signalCode === null)
+  const exits = running.map(({ process }) => once(process, "exit"))
+  running.forEach(({ process }) => process.stdin.end())
+  await Promise.all(exits)
+}
+
+async function waitForExit(child: Child): Promise<void> {
+  if (child.process.exitCode === null && child.process.signalCode === null) await once(child.process, "exit")
+}
+
+test("simultaneous acquisition across processes yields one owner", async (t) => {
+  const directory = temp(t), start = join(directory, "start")
+  const children = Array.from({ length: 4 }, () => child(directory, start))
+  try {
+    writeFileSync(start, "")
+    assert.equal((await Promise.all(children.map(({ result }) => result))).filter(Boolean).length, 1)
+  } finally { await stop(...children) }
+})
+
+test("owner publication crash leaves no visible owner", async (t) => {
+  const directory = temp(t), start = join(directory, "start")
+  const crashed = child(directory, start, "owner-crash")
+  writeFileSync(start, "")
+  await waitForExit(crashed)
+  assert.equal(existsSync(join(directory, CROSS_HOST_OWNER_DIRECTORY)), false)
+  const winner = CrossHostRegistration.register(directory, owner(101, "winner"), true, dependencies(true, "winner-start"))!
+  assert.equal(winner.isPrimary, true)
+})
+
+test("stale retirement crash cannot retire a successor", async (t) => {
+  const directory = temp(t), staleDirectory = join(directory, CROSS_HOST_OWNER_DIRECTORY)
+  mkdirSync(staleDirectory)
+  writeFileSync(join(staleDirectory, "owner.json"), JSON.stringify(owner(4_000_000_000, "stale")))
+  const start = join(directory, "start"), crashed = child(directory, start, "retire-crash")
+  writeFileSync(start, "")
+  await waitForExit(crashed)
+  const winner = CrossHostRegistration.register(directory, owner(102, "successor"), true, dependencies(true, "successor-start"))!
+  assert.equal(winner.isPrimary, true)
+  assert.equal(JSON.parse(readFileSync(ownerFile(directory), "utf8")).runToken, "successor")
+})
+
+test("stale recovery is identity guarded and blocked by non-claiming live participants", (t) => {
+  for (const value of [
+    { alive: false, identity: undefined, recover: true },
+    { alive: true, identity: "reused", recover: true },
+    { alive: true, identity: "old-start", recover: false },
+    { alive: true, identity: undefined, recover: false },
+  ]) {
+    const directory = temp(t), staleDirectory = join(directory, CROSS_HOST_OWNER_DIRECTORY)
+    mkdirSync(staleDirectory); writeFileSync(join(staleDirectory, "owner.json"), JSON.stringify(owner(201, "old", "old-start")))
+    const registration = CrossHostRegistration.register(directory, owner(202, "new"), true, dependencies(value.alive, value.identity))!
+    assert.equal(registration.isPrimary, value.recover)
+  }
+
+  const directory = temp(t), staleDirectory = join(directory, CROSS_HOST_OWNER_DIRECTORY)
+  mkdirSync(staleDirectory); writeFileSync(join(staleDirectory, "owner.json"), JSON.stringify(owner(301, "dead")))
+  writeFileSync(join(directory, "participant.302.secondary.json"), JSON.stringify(owner(302, "secondary")))
+  const identities = new Map([[302, "secondary-start"]])
+  const blocked = CrossHostRegistration.register(directory, owner(303, "next"), true, {
+    pidAlive: (pid) => pid === 302,
+    processStartIdentity: (pid) => identities.get(pid),
+  })!
+  assert.equal(blocked.isPrimary, false)
+})
+
+test("simultaneous claimants deterministically recover a stale owner", (t) => {
+  const directory = temp(t), staleDirectory = join(directory, CROSS_HOST_OWNER_DIRECTORY)
+  const stale = owner(601, "stale"), first = owner(602, "a"), second = owner(603, "b")
+  mkdirSync(staleDirectory)
+  const observed = JSON.stringify(stale)
+  writeFileSync(join(staleDirectory, "owner.json"), observed)
+  writeFileSync(join(directory, "participant.603.b.json"), JSON.stringify(second))
+  writeFileSync(join(directory, "recovery.603.b.claim"), observed)
+  const identities = new Map([[602, first.processStartIdentity], [603, second.processStartIdentity]])
+  const deps = {
+    pidAlive: (pid: number) => pid !== stale.pid,
+    processStartIdentity: (pid: number) => identities.get(pid),
+  }
+  const winner = CrossHostRegistration.register(directory, first, true, deps)!
+  const loser = CrossHostRegistration.register(directory, second, true, deps)!
+  assert.equal(winner.isPrimary, true)
+  assert.equal(loser.isPrimary, false)
+})
+
+test("graceful primary release allows a successor while a secondary remains", (t) => {
+  const directory = temp(t)
+  const primary = CrossHostRegistration.register(directory, owner(401, "primary"), true, dependencies(true, "primary-start"))!
+  const secondary = CrossHostRegistration.register(directory, owner(402, "secondary"), true, dependencies(true, "primary-start"))!
+  assert.equal(secondary.isPrimary, false)
+
+  assert.equal(primary.release(), true)
+  const successor = CrossHostRegistration.register(directory, owner(403, "successor"), true, dependencies(true, "successor-start"))!
+  assert.equal(successor.isPrimary, true)
+})
+
+test("graceful handoff retires the old cohort so a crashed successor can recover", (t) => {
+  const directory = temp(t), secondaryOwner = owner(422, "secondary"), successorOwner = owner(423, "successor"), lateOwner = owner(425, "late")
+  const malformed = join(directory, "participant.malformed.json")
+  const primary = CrossHostRegistration.register(directory, owner(421, "primary"), true, {
+    pidAlive: () => true,
+    processStartIdentity: () => "primary-start",
+    onGracefulOwnerChecked: () => {
+      writeFileSync(join(directory, "participant.423.successor.json"), JSON.stringify(successorOwner))
+      writeFileSync(join(directory, "participant.425.late.json"), JSON.stringify(lateOwner))
+      writeFileSync(malformed, "malformed")
+    },
+    onOwnerRetired: () => {
+      mkdirSync(join(directory, CROSS_HOST_OWNER_DIRECTORY))
+      writeFileSync(ownerFile(directory), JSON.stringify(successorOwner))
+    },
+  })!
+  CrossHostRegistration.register(directory, secondaryOwner, true, dependencies(true, "primary-start"))!
+
+  primary.release()
+  assert.equal(readdirSync(directory).some((name) => name.startsWith("retired.")), false)
+  assert.equal(JSON.parse(readFileSync(ownerFile(directory), "utf8")).runToken, "successor")
+  assert.equal(existsSync(join(directory, "participant.423.successor.json")), false)
+  assert.equal(existsSync(join(directory, "participant.425.late.json")), false)
+  assert.equal(existsSync(malformed), false)
+
+  const claimantOwner = owner(424, "claimant"), identities = new Map([
+    [secondaryOwner.pid, secondaryOwner.processStartIdentity],
+    [lateOwner.pid, lateOwner.processStartIdentity],
+    [claimantOwner.pid, claimantOwner.processStartIdentity],
+  ])
+  const claimant = CrossHostRegistration.register(directory, claimantOwner, true, {
+    pidAlive: (pid) => identities.has(pid),
+    processStartIdentity: (pid) => identities.get(pid),
+  })!
+  assert.equal(claimant.isPrimary, true)
+})
+
+test("non-owner release does not remove a live owner's record", (t) => {
+  const directory = temp(t)
+  const primary = CrossHostRegistration.register(directory, owner(411, "primary"), true, dependencies(true, "primary-start"))!
+  const secondary = CrossHostRegistration.register(directory, owner(412, "secondary"), true, dependencies(true, "primary-start"))!
+
+  assert.equal(secondary.release(), true)
+  assert.equal(primary.isPrimary, true)
+  assert.equal(JSON.parse(readFileSync(ownerFile(directory), "utf8")).runToken, "primary")
+})
+
+test("primary crash remains fenced by its non-claiming secondary cohort", async (t) => {
+  const directory = temp(t), firstStart = join(directory, "first-start")
+  const primary = child(directory, firstStart), secondary = child(directory, firstStart)
+  writeFileSync(firstStart, "")
+  const roles = await Promise.all([primary.result, secondary.result])
+  const winner = roles[0] ? primary : secondary, survivor = roles[0] ? secondary : primary
+  winner.process.kill()
+  await waitForExit(winner)
+  const blocked = CrossHostRegistration.register(directory, owner(501, "blocked"), true)!
+  assert.equal(blocked.isPrimary, false)
+  blocked.release()
+  survivor.process.kill()
+  await waitForExit(survivor)
+  const successor = CrossHostRegistration.register(directory, owner(502, "successor"), true)!
+  assert.equal(successor.isPrimary, true)
+})
+
+test("platform paths match the Rust contract", () => {
+  assert.equal(resolveCrossHostElectionDirectory({ HOME: "/Users/dev" }, "darwin", "/fallback"), posix.join("/Users/dev", ".codenomad", "client-state", "election"))
+  assert.equal(resolveCrossHostElectionDirectory({ HOME: "/home/dev" }, "linux", "/fallback"), posix.join("/home/dev", ".codenomad", "client-state", "election"))
+  assert.equal(resolveCrossHostElectionDirectory({ USERPROFILE: "", HOME: "D:\\Home" }, "win32", "C:\\Fallback"), win32.join("D:\\Home", ".codenomad", "client-state", "election"))
+  assert.equal(resolveCrossHostStatePath({ HOME: "/Users/dev" }, "darwin", "/fallback"), posix.join("/Users/dev", ".codenomad", "client-state", "client-state.json"))
+  assert.equal(resolveCrossHostStatePath({ HOME: "/home/dev" }, "linux", "/fallback"), posix.join("/home/dev", ".codenomad", "client-state", "client-state.json"))
+  assert.equal(resolveCrossHostStatePath({ USERPROFILE: "", HOME: "D:\\Home" }, "win32", "C:\\Fallback"), win32.join("D:\\Home", ".codenomad", "client-state", "client-state.json"))
+})
diff --git a/packages/electron-app/electron/main/client-state-cross-host.ts b/packages/electron-app/electron/main/client-state-cross-host.ts
new file mode 100644
index 00000000..33cbbd82
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-cross-host.ts
@@ -0,0 +1,344 @@
+import { randomUUID } from "node:crypto"
+import { closeSync, existsSync, fsyncSync, linkSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { basename, dirname, join, posix, win32 } from "node:path"
+import { getProcessStartIdentity, type ProcessStartIdentityLookup } from "./client-state-process-identity"
+import { hasErrorCode, isPidAlive, type ProcessOwner } from "./client-state-process"
+
+export const CROSS_HOST_OWNER_DIRECTORY = "primary.owner.json"
+const OWNER_FILENAME = "owner.json"
+const PARTICIPANT_PREFIX = "participant."
+const PARTICIPANT_SUFFIX = ".json"
+const RECOVERY_PREFIX = "recovery."
+const RECOVERY_SUFFIX = ".claim"
+const RETIRED_PREFIX = "retired."
+const ACQUIRE_ATTEMPTS = 10
+
+export interface CrossHostLeaseDependencies {
+  pidAlive(pid: number): boolean
+  processStartIdentity: ProcessStartIdentityLookup
+  onParticipantPublished?(): void
+  onOwnerPrepared?(): void
+  onOwnerRetired?(): void
+  onGracefulOwnerChecked?(): void
+}
+
+const defaultDependencies: CrossHostLeaseDependencies = {
+  pidAlive: isPidAlive,
+  processStartIdentity: getProcessStartIdentity,
+}
+
+function validHome(value: string | undefined, platform: NodeJS.Platform): string | undefined {
+  if (!value) return undefined
+  if (platform !== "win32") return posix.isAbsolute(value) ? value : undefined
+  return /^(?:[A-Za-z]:[\\/]|\\\\)/.test(value) ? value : undefined
+}
+
+export function resolveCrossHostElectionDirectory(
+  environment: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+  fallbackHome = homedir(),
+): string {
+  const pathApi = platform === "win32" ? win32 : posix
+  const configured = platform === "win32"
+    ? validHome(environment.USERPROFILE, platform) ?? validHome(environment.HOME, platform)
+    : validHome(environment.HOME, platform)
+  return pathApi.join(configured ?? fallbackHome, ".codenomad", "client-state", "election")
+}
+
+export function resolveCrossHostStatePath(
+  environment: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+  fallbackHome = homedir(),
+): string {
+  const pathApi = platform === "win32" ? win32 : posix
+  const configured = platform === "win32"
+    ? validHome(environment.USERPROFILE, platform) ?? validHome(environment.HOME, platform)
+    : validHome(environment.HOME, platform)
+  return pathApi.join(configured ?? fallbackHome, ".codenomad", "client-state", "client-state.json")
+}
+
+export function resolveLegacyTauriDataDirectory(
+  environment: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+  fallbackHome = homedir(),
+): string {
+  const pathApi = platform === "win32" ? win32 : posix
+  const home = platform === "win32"
+    ? validHome(environment.USERPROFILE, platform) ?? validHome(environment.HOME, platform) ?? fallbackHome
+    : validHome(environment.HOME, platform) ?? fallbackHome
+  const root = platform === "win32"
+    ? validHome(environment.APPDATA, platform) ?? pathApi.join(home, "AppData", "Roaming")
+    : platform === "darwin"
+      ? pathApi.join(home, "Library", "Application Support")
+      : validHome(environment.XDG_DATA_HOME, platform) ?? pathApi.join(home, ".local", "share")
+  return pathApi.join(root, "ai.neuralnomads.codenomad.client")
+}
+
+export function createCrossHostOwner(): ProcessOwner | undefined {
+  const processStartIdentity = getProcessStartIdentity(process.pid)
+  return processStartIdentity ? { pid: process.pid, runToken: randomUUID(), processStartIdentity } : undefined
+}
+
+function serializeOwner(owner: ProcessOwner): string {
+  return JSON.stringify({ pid: owner.pid, runToken: owner.runToken, processStartIdentity: owner.processStartIdentity })
+}
+
+function parseOwner(value: string): ProcessOwner | undefined {
+  try {
+    const owner = JSON.parse(value) as Partial<ProcessOwner>
+    if (Number.isInteger(owner.pid) && Number(owner.pid) > 0 && Number(owner.pid) <= 0xffff_ffff &&
+      typeof owner.runToken === "string" && /^[A-Za-z0-9_-]+$/.test(owner.runToken) &&
+      typeof owner.processStartIdentity === "string" && owner.processStartIdentity) {
+      return { pid: Number(owner.pid), runToken: owner.runToken, processStartIdentity: owner.processStartIdentity }
+    }
+  } catch {}
+  return undefined
+}
+
+function sameOwner(left: ProcessOwner, right: ProcessOwner): boolean {
+  return left.pid === right.pid && left.runToken === right.runToken && left.processStartIdentity === right.processStartIdentity
+}
+
+function readIfExists(path: string): string | undefined {
+  try { return readFileSync(path, "utf8") } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) return undefined
+    throw error
+  }
+}
+
+function sync(descriptor: number): void {
+  try { fsyncSync(descriptor) } catch (error) {
+    if (!["EINVAL", "ENOTSUP", "ENOSYS"].some((code) => hasErrorCode(error, code))) throw error
+  }
+}
+
+function publishFile(path: string, value: string): void {
+  const temporary = join(dirname(path), `.publish.${randomUUID()}.tmp`)
+  let descriptor: number | undefined
+  try {
+    descriptor = openSync(temporary, "wx", 0o600)
+    writeFileSync(descriptor, value, "utf8")
+    sync(descriptor)
+    closeSync(descriptor)
+    descriptor = undefined
+    linkSync(temporary, path)
+  } finally {
+    if (descriptor !== undefined) try { closeSync(descriptor) } catch {}
+    try { unlinkSync(temporary) } catch {}
+  }
+}
+
+function participantPath(directory: string, owner: ProcessOwner): string {
+  return join(directory, `${PARTICIPANT_PREFIX}${owner.pid}.${owner.runToken}${PARTICIPANT_SUFFIX}`)
+}
+
+function recoveryPath(directory: string, owner: ProcessOwner): string {
+  return join(directory, `${RECOVERY_PREFIX}${owner.pid}.${owner.runToken}${RECOVERY_SUFFIX}`)
+}
+
+function publishParticipant(path: string, owner: ProcessOwner): void {
+  const value = serializeOwner(owner)
+  try { publishFile(path, value) } catch (error) {
+    if (!hasErrorCode(error, "EEXIST") || readIfExists(path) !== value) throw error
+  }
+}
+
+function ownerPath(directory: string): string {
+  return join(directory, CROSS_HOST_OWNER_DIRECTORY, OWNER_FILENAME)
+}
+
+function ownerIsStale(owner: ProcessOwner, dependencies: CrossHostLeaseDependencies): boolean | undefined {
+  if (!dependencies.pidAlive(owner.pid)) return true
+  const identity = dependencies.processStartIdentity(owner.pid)
+  return identity ? identity !== owner.processStartIdentity : undefined
+}
+
+function removeParticipantIfOwned(path: string, owner: ProcessOwner): void {
+  const observed = readIfExists(path)
+  const current = observed === undefined ? undefined : parseOwner(observed)
+  if (!current || !sameOwner(current, owner)) return
+  try { unlinkSync(path) } catch (error) {
+    if (!hasErrorCode(error, "ENOENT")) throw error
+  }
+}
+
+function retireOwnerIfOwned(directory: string, owner: ProcessOwner, dependencies: CrossHostLeaseDependencies): void {
+  const observed = readIfExists(ownerPath(directory))
+  const current = parseOwner(observed ?? "")
+  if (!current || !sameOwner(current, owner)) return
+  dependencies.onGracefulOwnerChecked?.()
+  if (readIfExists(ownerPath(directory)) !== observed) return
+  const retired = join(directory, `${RETIRED_PREFIX}${owner.pid}.${owner.runToken}`)
+  try { renameSync(join(directory, CROSS_HOST_OWNER_DIRECTORY), retired) } catch (error) {
+    if (["ENOENT", "EEXIST", "ENOTEMPTY"].some((code) => hasErrorCode(error, code)) || existsSync(retired)) return
+    throw error
+  }
+  try {
+    dependencies.onOwnerRetired?.()
+    for (const name of readdirSync(directory)) {
+      if (!name.startsWith(PARTICIPANT_PREFIX) || !name.endsWith(PARTICIPANT_SUFFIX)) continue
+      const path = join(directory, name), observedParticipant = readIfExists(path)
+      if (observedParticipant === undefined) continue
+      const participant = parseOwner(observedParticipant)
+      if (participant) {
+        removeParticipantIfOwned(path, participant)
+        try { unlinkSync(recoveryPath(directory, participant)) } catch {}
+      } else if (readIfExists(path) === observedParticipant) {
+        try { unlinkSync(path) } catch (error) {
+          if (!hasErrorCode(error, "ENOENT")) throw error
+        }
+      }
+    }
+  } finally {
+    try { rmSync(retired, { recursive: true, force: true }) } catch {}
+  }
+}
+
+function recoveryClaimants(
+  directory: string,
+  current: ProcessOwner,
+  observedOwner: string,
+  dependencies: CrossHostLeaseDependencies,
+): ProcessOwner[] | undefined {
+  const claimants = [current]
+  for (const name of readdirSync(directory)) {
+    if (!name.startsWith(PARTICIPANT_PREFIX) || !name.endsWith(PARTICIPANT_SUFFIX)) continue
+    const path = join(directory, name)
+    const participant = parseOwner(readIfExists(path) ?? "")
+    if (!participant) return undefined
+    if (sameOwner(participant, current)) continue
+    const stale = ownerIsStale(participant, dependencies)
+    if (stale === true) {
+      removeParticipantIfOwned(path, participant)
+      try { unlinkSync(recoveryPath(directory, participant)) } catch {}
+      continue
+    }
+    const claimPath = recoveryPath(directory, participant)
+    let claim = readIfExists(claimPath)
+    for (let attempt = 0; claim !== observedOwner && attempt < 20; attempt += 1) {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5)
+      claim = readIfExists(claimPath)
+    }
+    if (claim !== observedOwner) return undefined
+    claimants.push(participant)
+  }
+  return claimants
+}
+
+function retireOwner(directory: string, observed: string, owner: ProcessOwner, claimant: ProcessOwner, dependencies: CrossHostLeaseDependencies): boolean {
+  if (ownerIsStale(owner, dependencies) !== true) return false
+  const claimants = recoveryClaimants(directory, claimant, observed, dependencies)
+  if (!claimants) return false
+  claimants.sort((left, right) => serializeOwner(left) < serializeOwner(right) ? -1 : 1)
+  if (!sameOwner(claimants[0]!, claimant)) return false
+  if (readIfExists(ownerPath(directory)) !== observed) return false
+  const retired = join(directory, `${RETIRED_PREFIX}${owner.pid}.${owner.runToken}`)
+  try {
+    renameSync(join(directory, CROSS_HOST_OWNER_DIRECTORY), retired)
+    dependencies.onOwnerRetired?.()
+    return true
+  } catch (error) {
+    if (["ENOENT", "EEXIST", "ENOTEMPTY"].some((code) => hasErrorCode(error, code)) || existsSync(retired)) return false
+    throw error
+  }
+}
+
+function publishOwner(directory: string, owner: ProcessOwner, dependencies: CrossHostLeaseDependencies): boolean {
+  const temporary = join(directory, `.owner.${randomUUID()}.tmp`)
+  try {
+    mkdirSync(temporary, { mode: 0o700 })
+    const descriptor = openSync(join(temporary, OWNER_FILENAME), "wx", 0o600)
+    try { writeFileSync(descriptor, serializeOwner(owner), "utf8"); sync(descriptor) } finally { closeSync(descriptor) }
+    dependencies.onOwnerPrepared?.()
+    renameSync(temporary, join(directory, CROSS_HOST_OWNER_DIRECTORY))
+    return true
+  } catch (error) {
+    if (hasErrorCode(error, "EEXIST") || hasErrorCode(error, "ENOTEMPTY") || existsSync(join(directory, CROSS_HOST_OWNER_DIRECTORY))) return false
+    throw error
+  } finally {
+    try { rmSync(temporary, { recursive: true, force: true }) } catch {}
+  }
+}
+
+export function crossHostParticipants(directory: string): ProcessOwner[] {
+  try {
+    return readdirSync(directory)
+      .filter((name) => name.startsWith(PARTICIPANT_PREFIX) && name.endsWith(PARTICIPANT_SUFFIX))
+      .map((name) => parseOwner(readIfExists(join(directory, name)) ?? ""))
+      .filter((owner): owner is ProcessOwner => Boolean(owner))
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) return []
+    throw error
+  }
+}
+
+export class CrossHostRegistration {
+  private released = false
+
+  private constructor(
+    private readonly directory: string,
+    readonly owner: ProcessOwner,
+    private readonly participant: string,
+    private readonly recoveryClaim: string | undefined,
+    private primary: boolean,
+    private readonly dependencies: CrossHostLeaseDependencies,
+  ) {}
+
+  get path(): string { return this.directory }
+
+  static register(
+    directory: string,
+    owner: ProcessOwner,
+    primaryCandidate: boolean | (() => boolean),
+    dependencies: CrossHostLeaseDependencies = defaultDependencies,
+  ): CrossHostRegistration | undefined {
+    if (!owner.processStartIdentity || !/^[A-Za-z0-9_-]+$/.test(owner.runToken)) return undefined
+    mkdirSync(directory, { recursive: true, mode: 0o700 })
+    const participant = participantPath(directory, owner)
+    publishParticipant(participant, owner)
+    dependencies.onParticipantPublished?.()
+    let primary = false
+    let recoveryClaim: string | undefined
+    try {
+      if (typeof primaryCandidate === "function" ? primaryCandidate() : primaryCandidate) {
+        for (let attempt = 0; attempt < ACQUIRE_ATTEMPTS; attempt += 1) {
+          if (publishOwner(directory, owner, dependencies)) { primary = true; break }
+          const observed = readIfExists(ownerPath(directory))
+          if (observed === undefined) continue
+          const existing = parseOwner(observed)
+          if (!existing) break
+          if (sameOwner(existing, owner)) { primary = true; break }
+          if (ownerIsStale(existing, dependencies) === true) {
+            recoveryClaim ??= recoveryPath(directory, owner)
+            try { publishFile(recoveryClaim, observed) } catch (error) {
+              if (!hasErrorCode(error, "EEXIST") || readIfExists(recoveryClaim) !== observed) throw error
+            }
+          }
+          if (!retireOwner(directory, observed, existing, owner, dependencies)) break
+        }
+      }
+      return new CrossHostRegistration(directory, owner, participant, recoveryClaim, primary, dependencies)
+    } catch (error) {
+      removeParticipantIfOwned(participant, owner)
+      if (recoveryClaim) try { unlinkSync(recoveryClaim) } catch {}
+      throw error
+    }
+  }
+
+  get isPrimary(): boolean {
+    if (this.released || !this.primary) return false
+    const current = parseOwner(readIfExists(ownerPath(this.directory)) ?? "")
+    return Boolean(current && sameOwner(current, this.owner))
+  }
+
+  release(): boolean {
+    if (this.released) return false
+    retireOwnerIfOwned(this.directory, this.owner, this.dependencies)
+    removeParticipantIfOwned(this.participant, this.owner)
+    if (this.recoveryClaim) try { unlinkSync(this.recoveryClaim) } catch {}
+    this.primary = false
+    this.released = true
+    return true
+  }
+}
diff --git a/packages/electron-app/electron/main/client-state-election-child.ts b/packages/electron-app/electron/main/client-state-election-child.ts
new file mode 100644
index 00000000..4b4db1bf
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-election-child.ts
@@ -0,0 +1,62 @@
+import { existsSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import {
+  electClientStateProcess,
+  isPidAlive,
+  REGISTRATION_LOCK_WAIT_MS,
+  removeProcessOwnerLockIfOwned,
+  removeRunningMarkerIfOwned,
+  type ProcessOwner,
+} from "./client-state-process"
+import { getProcessStartIdentity } from "./client-state-process-identity"
+
+const [directory, runToken, startPath, registrationWaitArgument, primaryPausedPath, primaryReleasePath] =
+  process.argv.slice(2)
+if (!directory || !runToken || !startPath) {
+  throw new Error("Expected election directory, run token, and start path")
+}
+
+while (!existsSync(startPath)) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5)
+}
+
+const owner: ProcessOwner = {
+  pid: process.pid,
+  runToken,
+  processStartIdentity: getProcessStartIdentity(process.pid),
+}
+const primaryLockPath = join(directory, "client-state.primary.lock")
+const registrationLockPath = join(directory, "client-state.registration.lock")
+const registrationLockWaitMs = registrationWaitArgument
+  ? Number(registrationWaitArgument)
+  : REGISTRATION_LOCK_WAIT_MS
+const warnings: string[] = []
+const election = electClientStateProcess(
+  directory,
+  owner,
+  { primaryLockPath, registrationLockPath },
+  (message, error) => warnings.push(`${message}: ${String(error)}`),
+  isPidAlive,
+  registrationLockWaitMs,
+  () => {
+    if (!primaryPausedPath || !primaryReleasePath) {
+      return
+    }
+    try {
+      writeFileSync(primaryPausedPath, JSON.stringify(owner), { encoding: "utf8", flag: "wx" })
+    } catch {
+      // Only the contender that published the synchronization point owns the pause gate.
+      return
+    }
+    while (!existsSync(primaryReleasePath)) {
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5)
+    }
+  },
+)
+
+process.stdout.write(`${JSON.stringify({ isPrimary: election, owner, warnings })}\n`)
+process.stdin.resume()
+process.stdin.once("end", () => {
+  removeRunningMarkerIfOwned(join(directory, `client-state.running.${owner.pid}.${owner.runToken}.json`), owner)
+  removeProcessOwnerLockIfOwned(primaryLockPath, owner)
+})
diff --git a/packages/electron-app/electron/main/client-state-ipc.test.ts b/packages/electron-app/electron/main/client-state-ipc.test.ts
new file mode 100644
index 00000000..15f1698e
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-ipc.test.ts
@@ -0,0 +1,64 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import type { IpcMainInvokeEvent } from "electron"
+import { setupClientStateIPC } from "./client-state-ipc"
+
+function harness() {
+  const handlers = new Map<string, (event: IpcMainInvokeEvent, ...args: unknown[]) => unknown>()
+  const listeners = new Map<string, (...args: unknown[]) => void>()
+  const frame = { url: "http://127.0.0.1:3000/app" }
+  const webContents = {
+    mainFrame: frame,
+    getURL: () => "http://127.0.0.1:3000/app",
+    on: (event: string, listener: (...args: unknown[]) => void) => listeners.set(event, listener),
+  }
+  const window = { isDestroyed: () => false, webContents }
+  let current: typeof window | null = window
+  const calls: string[] = []
+  const state = {
+    claimClientStateAccess: (token: unknown) => { calls.push(`claim:${token}`); return true },
+    assertRendererAccessToken: (token: unknown) => calls.push(`assert:${token}`),
+    loadClientState: () => ({ isPrimary: true }),
+    saveClientState: () => true,
+    setRestoreEnabled: () => true,
+    clearClientState: () => true,
+    resetRendererAccessToken: () => calls.push("reset"),
+  }
+  const bind = setupClientStateIPC(
+    { handle: (channel, listener) => handlers.set(channel, listener) },
+    state as never,
+    () => current as never,
+    () => ["http://127.0.0.1:3000"],
+  )
+  bind(window as never)
+  return { calls, frame, handlers, listeners, setCurrent: (value: typeof window | null) => { current = value }, webContents, window }
+}
+
+test("IPC channels enforce the current main sender, frame, origin, and token", async () => {
+  const h = harness()
+  assert.deepEqual([...h.handlers.keys()], [
+    "client-state:claimAccess", "client-state:load", "client-state:save",
+    "client-state:setRestoreEnabled", "client-state:clear",
+  ])
+  const event = { sender: h.webContents, senderFrame: h.frame }
+  await h.handlers.get("client-state:claimAccess")!(event as never, "token")
+  await h.handlers.get("client-state:load")!(event as never, "token")
+  assert.deepEqual(h.calls, ["claim:token", "assert:token"])
+
+  for (const invalid of [
+    { sender: {}, senderFrame: h.frame },
+    { sender: h.webContents, senderFrame: { url: h.frame.url } },
+    { sender: h.webContents, senderFrame: { ...h.frame, url: "https://example.com" } },
+  ]) await assert.rejects(h.handlers.get("client-state:load")!(invalid as never, "token") as Promise<unknown>)
+})
+
+test("only the registered current window can reset renderer authority", () => {
+  const h = harness()
+  h.listeners.get("did-navigate")!({}, "http://127.0.0.1:3000/next")
+  h.listeners.get("render-process-gone")!()
+  assert.deepEqual(h.calls, ["reset", "reset"])
+  h.setCurrent(null)
+  h.listeners.get("did-navigate")!({}, "http://127.0.0.1:3000/late")
+  h.listeners.get("destroyed")!()
+  assert.deepEqual(h.calls, ["reset", "reset"])
+})
diff --git a/packages/electron-app/electron/main/client-state-ipc.ts b/packages/electron-app/electron/main/client-state-ipc.ts
new file mode 100644
index 00000000..51b0b0c5
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-ipc.ts
@@ -0,0 +1,78 @@
+import type { BrowserWindow, IpcMainInvokeEvent } from "electron"
+import type { ClientStateManager } from "./client-state"
+import { shouldResetRendererAccessTokenForNavigation } from "./client-state-navigation"
+import { isAllowedRendererOrigin } from "./renderer-origin"
+
+interface IPCRegistrar {
+  handle(channel: string, listener: (event: IpcMainInvokeEvent, ...args: unknown[]) => unknown): void
+}
+
+function validateSender(event: IpcMainInvokeEvent, mainWindow: BrowserWindow | null, allowedOrigins: string[]) {
+  if (
+    !mainWindow ||
+    mainWindow.isDestroyed() ||
+    event.sender !== mainWindow.webContents ||
+    event.senderFrame !== mainWindow.webContents.mainFrame
+  ) {
+    throw new Error("Client state IPC is only available to the local main window")
+  }
+
+  const currentUrl = mainWindow.webContents.getURL()
+  if (
+    !isAllowedRendererOrigin(currentUrl, allowedOrigins) ||
+    !isAllowedRendererOrigin(event.senderFrame.url, allowedOrigins) ||
+    new URL(currentUrl).origin !== new URL(event.senderFrame.url).origin
+  ) {
+    throw new Error("Client state IPC is not available to the current renderer origin")
+  }
+}
+
+export function setupClientStateIPC(
+  ipcMain: IPCRegistrar,
+  clientState: ClientStateManager,
+  getMainWindow: () => BrowserWindow | null,
+  getAllowedOrigins: (window: BrowserWindow | null) => string[],
+) {
+  const validate = (event: IpcMainInvokeEvent) => {
+    const window = getMainWindow()
+    validateSender(event, window, getAllowedOrigins(window))
+  }
+  const handle = (
+    channel: string,
+    operation: (argument: unknown, token: unknown) => unknown,
+  ) => ipcMain.handle(channel, async (event, token: unknown, argument: unknown) => {
+    validate(event)
+    clientState.assertRendererAccessToken(token)
+    return operation(argument, token)
+  })
+
+  ipcMain.handle("client-state:claimAccess", async (event, token: unknown) => {
+    validate(event)
+    return clientState.claimClientStateAccess(token)
+  })
+  handle("client-state:load", () => clientState.loadClientState())
+  handle("client-state:save", (snapshot, token) => clientState.saveClientState(snapshot, token))
+  handle("client-state:setRestoreEnabled", (enabled, token) => {
+    if (typeof enabled !== "boolean") throw new Error("Restore enabled must be a boolean")
+    return clientState.setRestoreEnabled(enabled, token)
+  })
+  handle("client-state:clear", (_argument, token) => clientState.clearClientState(token))
+
+  return (window: BrowserWindow): void => {
+    window.webContents.on("did-navigate", (_event, url) => {
+      if (getMainWindow() === window && shouldResetRendererAccessTokenForNavigation(
+        url,
+        false,
+        true,
+        (target) => isAllowedRendererOrigin(target, getAllowedOrigins(window)),
+      )) {
+        clientState.resetRendererAccessToken()
+      }
+    })
+    const resetDestroyedRenderer = () => {
+      if (getMainWindow() === window) clientState.resetRendererAccessToken()
+    }
+    window.webContents.on("render-process-gone", resetDestroyedRenderer)
+    window.webContents.on("destroyed", resetDestroyedRenderer)
+  }
+}
diff --git a/packages/electron-app/electron/main/client-state-lifecycle.test.ts b/packages/electron-app/electron/main/client-state-lifecycle.test.ts
new file mode 100644
index 00000000..9f65b211
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-lifecycle.test.ts
@@ -0,0 +1,159 @@
+import assert from "node:assert/strict"
+import { setTimeout as delay } from "node:timers/promises"
+import test from "node:test"
+import type { App, BrowserWindow } from "electron"
+import { ClientStateLifecycle } from "./client-state-lifecycle"
+import type { ClientStateManager } from "./client-state"
+import type { CliProcessManager } from "./process-manager"
+import type { WindowStateTracker } from "./window-state"
+
+const tick = () => new Promise((resolve) => setImmediate(resolve))
+function harness(options: {
+  flush?: () => Promise<unknown>
+  stop?: () => Promise<void>
+  nativeFlush?: () => Promise<void>
+  otherWindow?: boolean
+  sessionEndCleanupTimeoutMs?: number
+  sessionEndReleaseTimeoutMs?: number
+  release?: () => Promise<void>
+} = {}) {
+  const windows = new Map<string, (event?: { preventDefault(): void }) => void>()
+  const appEvents = new Map<string, (event?: { preventDefault(): void }) => void>()
+  const calls: string[] = []
+  let exits = 0
+  const window = {
+    on: (name: string, handler: (event?: { preventDefault(): void }) => void) => windows.set(name, handler),
+    isDestroyed: () => false,
+    close: () => { calls.push("close"); windows.get("close")?.({ preventDefault: () => assert.fail("approved close prevented") }) },
+    hide: () => { calls.push("hide") },
+    show: () => { calls.push("show") },
+    webContents: { isDestroyed: () => false, getURL: () => "http://127.0.0.1:43123/workspace", executeJavaScript: () => { calls.push("renderer"); return options.flush?.() ?? Promise.resolve() } },
+  } as unknown as BrowserWindow
+  const other = { isDestroyed: () => false, hide: () => { calls.push("hide-other") } } as unknown as BrowserWindow
+  const app = { on: (name: string, handler: never) => appEvents.set(name, handler), quit: () => calls.push("quit"), exit: () => { exits++ } } as unknown as App
+  const manager = { isPrimary: true, flush: async () => {}, drainAndReleasePrimary: async () => { calls.push("release"); await options.release?.() } } as ClientStateManager
+  const cli = { shutdown: async () => { calls.push("stop"); await options.stop?.() } } as unknown as CliProcessManager
+  const lifecycle = new ClientStateLifecycle({ app, clientStateManager: manager, cliManager: cli, getMainWindow: () => window, getAllWindows: () => options.otherWindow ? [window, other] : [window], getAllowedRendererOrigins: () => ["http://127.0.0.1:43123"], isTrustedRendererOrigin: () => true, isWindows: true, sessionEndCleanupTimeoutMs: options.sessionEndCleanupTimeoutMs, sessionEndReleaseTimeoutMs: options.sessionEndReleaseTimeoutMs })
+  lifecycle.attachMainWindow(window, { flush: async () => { calls.push("native"); await options.nativeFlush?.() } } as unknown as WindowStateTracker)
+  lifecycle.registerAppEvents()
+  const close = () => { let prevented = false; windows.get("close")?.({ preventDefault: () => { prevented = true } }); return prevented }
+  return { appEvents, calls, close, exits: () => exits, lifecycle, window, windows }
+}
+
+test("close flushes renderer/native once before approval, even when repeated or renderer fails", async (t) => {
+  await t.test("ordinary", async () => {
+    const h = harness({ otherWindow: true })
+    assert.equal(h.close(), true)
+    await tick()
+    assert.deepEqual(h.calls, ["renderer", "native", "close"])
+  })
+  await t.test("coalesced", async () => {
+    let release!: () => void
+    const h = harness({ otherWindow: true, flush: () => new Promise<void>((resolve) => { release = resolve }) })
+    assert.equal(h.close(), true); assert.equal(h.close(), true)
+    assert.deepEqual(h.calls, ["renderer"])
+    release(); await tick()
+    assert.deepEqual(h.calls, ["renderer", "native", "close"])
+  })
+  await t.test("renderer failure", async () => {
+    const h = harness({ otherWindow: true, flush: async () => { throw new Error("failed") } })
+    assert.equal(h.close(), true); await tick()
+    assert.deepEqual(h.calls, ["renderer", "native", "close"])
+  })
+})
+
+test("late old-window detach preserves replacement tracker during shutdown", async () => {
+  const h = harness()
+  const replacement = { on: () => {} } as unknown as BrowserWindow
+  h.lifecycle.attachMainWindow(replacement, { flush: async () => { h.calls.push("replacement-native") } } as unknown as WindowStateTracker)
+  h.lifecycle.detachMainWindow(h.window)
+  h.appEvents.get("before-quit")?.({ preventDefault: () => {} })
+  await (h.lifecycle as any).shutdown
+  assert.deepEqual(h.calls, ["hide", "renderer", "replacement-native", "stop", "release"])
+})
+
+test("Windows session end vetoes termination until cleanup exits explicitly", async () => {
+  const h = harness()
+  let prevented = false
+  h.windows.get("query-session-end")?.({ preventDefault: () => { prevented = true } })
+  h.windows.get("session-end")?.()
+  await (h.lifecycle as any).sessionEnd; await tick()
+  assert.equal(prevented, true)
+  assert.deepEqual(h.calls, ["renderer", "native", "stop", "release"])
+  assert.equal(h.exits(), 1)
+})
+
+test("session end force-exits after the bounded window when an ordinary shutdown is hung", async () => {
+  const h = harness({ flush: () => new Promise(() => {}), sessionEndCleanupTimeoutMs: 10 })
+  let prevented = false
+  h.appEvents.get("before-quit")?.({ preventDefault: () => {} })
+  h.windows.get("query-session-end")?.({ preventDefault: () => { prevented = true } })
+  await delay(25)
+  assert.equal(prevented, true)
+  assert.deepEqual(h.calls, ["hide", "renderer", "release"])
+  assert.equal(h.exits(), 1)
+})
+
+test("ordinary quit hides promptly and waits for CLI stop confirmation", async () => {
+  let confirmStop!: () => void
+  const h = harness({ stop: () => new Promise<void>((resolve) => { confirmStop = resolve }) })
+  h.appEvents.get("before-quit")?.({ preventDefault: () => {} })
+  await tick()
+  assert.deepEqual(h.calls, ["hide", "renderer", "native", "stop"])
+  assert.equal(h.exits(), 0)
+  confirmStop()
+  await (h.lifecycle as any).shutdown; await tick()
+  assert.deepEqual(h.calls, ["hide", "renderer", "native", "stop", "release"])
+  assert.equal(h.exits(), 1)
+})
+
+test("ordinary quit does not exit when CLI cleanup is unconfirmed", async () => {
+  const h = harness({ stop: async () => { throw new Error("unconfirmed") } })
+  h.appEvents.get("before-quit")?.({ preventDefault: () => {} })
+  await assert.rejects((h.lifecycle as any).shutdown, /unconfirmed/)
+  await tick()
+  assert.equal(h.exits(), 0)
+  assert.deepEqual(h.calls, ["hide", "renderer", "native", "stop", "show"])
+})
+
+test("Windows session-end rejection fails open at the bounded deadline", async () => {
+  const h = harness({ stop: async () => { throw new Error("unconfirmed") }, sessionEndCleanupTimeoutMs: 10 })
+  h.appEvents.get("before-quit")?.({ preventDefault: () => {} })
+  h.windows.get("query-session-end")?.({ preventDefault: () => {} })
+  await delay(25)
+  assert.equal(h.exits(), 1)
+  assert.deepEqual(h.calls, ["hide", "renderer", "native", "stop", "release"])
+})
+
+test("Windows fail-open bounds a hanging primary release before app.exit", async () => {
+  const h = harness({
+    flush: () => new Promise(() => {}),
+    release: () => new Promise(() => {}),
+    sessionEndCleanupTimeoutMs: 30,
+    sessionEndReleaseTimeoutMs: 10,
+  })
+  h.windows.get("query-session-end")?.({ preventDefault: () => {} })
+
+  await delay(25)
+  assert.deepEqual(h.calls, ["renderer", "release"])
+  assert.equal(h.exits(), 0)
+  await delay(15)
+  assert.equal(h.exits(), 1)
+})
+
+test("CLI termination waits for the native snapshot flush", async () => {
+  let release!: () => void
+  const h = harness({ nativeFlush: () => new Promise<void>((resolve) => { release = resolve }) })
+  h.appEvents.get("before-quit")?.({ preventDefault: () => {} })
+  await tick()
+  assert.deepEqual(h.calls, ["hide", "renderer", "native"])
+  assert.equal(h.exits(), 0)
+  release(); await (h.lifecycle as any).shutdown
+  assert.deepEqual(h.calls, ["hide", "renderer", "native", "stop", "release"])
+})
+
+test("closing the final window hides it before requesting quit", () => {
+  const h = harness()
+  assert.equal(h.close(), true)
+  assert.deepEqual(h.calls, ["hide", "quit"])
+})
diff --git a/packages/electron-app/electron/main/client-state-lifecycle.ts b/packages/electron-app/electron/main/client-state-lifecycle.ts
new file mode 100644
index 00000000..c0e7405c
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-lifecycle.ts
@@ -0,0 +1,192 @@
+import type { App, BrowserWindow } from "electron"
+import type { ClientStateManager } from "./client-state"
+import type { CliProcessManager } from "./process-manager"
+import { flushRendererClientStateBeforeShutdown } from "./renderer-client-state-flush"
+import type { WindowStateTracker } from "./window-state"
+
+interface ClientStateLifecycleDependencies {
+  app: App
+  clientStateManager: ClientStateManager
+  cliManager: CliProcessManager
+  getMainWindow(): BrowserWindow | null
+  getAllWindows(): BrowserWindow[]
+  getAllowedRendererOrigins(window?: BrowserWindow | null): string[]
+  isTrustedRendererOrigin(url: string, allowedOrigins: string[]): boolean
+  rendererFlushTimeoutMs?: number
+  sessionEndCleanupTimeoutMs?: number
+  sessionEndReleaseTimeoutMs?: number
+  isWindows?: boolean
+}
+
+export class ClientStateLifecycle {
+  private shutdown: Promise<void> | null = null
+  private sessionEnd: Promise<void> | null = null
+  private exitAllowed = false
+  private trackedMainWindow: BrowserWindow | null = null
+  private windowStateTracker: WindowStateTracker | null = null
+  private windowsHiddenForShutdown = false
+  private primaryRelease: Promise<void> | null = null
+
+  constructor(private readonly dependencies: ClientStateLifecycleDependencies) {}
+
+  attachMainWindow(window: BrowserWindow, tracker: WindowStateTracker | null): void {
+    this.trackedMainWindow = window
+    this.windowStateTracker = tracker
+    let closeApproved = false
+    let closeInProgress = false
+
+    window.on("close", (event) => {
+      if (this.exitAllowed || closeApproved) return
+      event.preventDefault()
+      if (this.shutdown) return
+
+      const hasOtherWindow = this.dependencies
+        .getAllWindows()
+        .some((candidate) => candidate !== window && !candidate.isDestroyed())
+      if (!hasOtherWindow) {
+        window.hide()
+        this.dependencies.app.quit()
+      } else if (!closeInProgress) {
+        closeInProgress = true
+        void this.flushForClose(window).finally(() => {
+          closeApproved = true
+          try {
+            window.close()
+          } catch (error) {
+            closeApproved = false
+            closeInProgress = false
+            console.warn("[client-state] main-window close failed", error)
+          }
+        })
+      }
+    })
+
+    if (this.dependencies.isWindows ?? process.platform === "win32") {
+      window.on("query-session-end", (event) => {
+        if (this.exitAllowed) return
+        event.preventDefault()
+        this.promoteToSessionEnd(window)
+      })
+      window.on("session-end", () => this.promoteToSessionEnd(window))
+    }
+  }
+
+  detachMainWindow(window: BrowserWindow): void {
+    if (this.trackedMainWindow !== window) return
+    this.trackedMainWindow = null
+    this.windowStateTracker = null
+  }
+
+  registerAppEvents(): void {
+    const { app } = this.dependencies
+    app.on("before-quit", (event) => {
+      if (this.exitAllowed) return
+      event.preventDefault()
+      this.hideWindows()
+      void this.startShutdown(this.dependencies.getMainWindow()).then(() => this.exit(), (error) => {
+        if (!this.sessionEnd) this.restoreWindowAfterRejectedShutdown(this.dependencies.getMainWindow())
+        console.warn("[client-state] desktop shutdown remains pending because cleanup was not contained", error)
+      })
+    })
+    app.on("window-all-closed", () => app.quit())
+  }
+
+  private async flushForClose(window: BrowserWindow): Promise<void> {
+    await this.runStage("renderer main-window close flush", () => this.flushRenderer(window))
+    await this.runStage("native main-window close flush", () => this.flushNative())
+  }
+
+  private startShutdown(window: BrowserWindow | null): Promise<void> {
+    if (this.shutdown) return this.shutdown
+    const stages = (async () => {
+      await this.runStage("renderer shutdown flush", () => this.flushRenderer(window))
+      await this.runStage("native shutdown flush", () => this.flushNative())
+      await this.dependencies.cliManager.shutdown()
+      await this.releasePrimary()
+    })()
+    this.shutdown = stages.catch((error) => {
+      this.shutdown = null
+      throw error
+    })
+    return this.shutdown
+  }
+
+  private hideWindows(): void {
+    for (const window of this.dependencies.getAllWindows()) {
+      if (!window.isDestroyed()) {
+        window.hide()
+        this.windowsHiddenForShutdown = true
+      }
+    }
+  }
+
+  private restoreWindowAfterRejectedShutdown(preferred: BrowserWindow | null): void {
+    if (!this.windowsHiddenForShutdown) return
+    this.windowsHiddenForShutdown = false
+    const window = preferred && !preferred.isDestroyed()
+      ? preferred
+      : this.dependencies.getAllWindows().find((candidate) => !candidate.isDestroyed())
+    if (window) window.show()
+  }
+
+  private promoteToSessionEnd(window: BrowserWindow): void {
+    if (this.exitAllowed || this.sessionEnd) return
+    const cleanup = this.startShutdown(window)
+    this.sessionEnd = new Promise<void>((resolve) => {
+      const timeoutMs = this.dependencies.sessionEndCleanupTimeoutMs ?? 5_000
+      const releaseTimeoutMs = Math.min(timeoutMs, this.dependencies.sessionEndReleaseTimeoutMs ?? 250)
+      const releaseTimer = setTimeout(() => {
+        void this.releasePrimary()
+      }, Math.max(0, timeoutMs - releaseTimeoutMs))
+      const exitTimer = setTimeout(() => {
+        console.warn(`[client-state] OS session-end cleanup exceeded ${timeoutMs}ms; exiting without containment`)
+        resolve()
+      }, timeoutMs)
+      void cleanup.then(() => {
+        clearTimeout(releaseTimer)
+        clearTimeout(exitTimer)
+        resolve()
+      }, (error) => {
+        console.warn("[client-state] OS session-end cleanup was not contained; waiting for forced exit", error)
+      })
+    }).then(() => this.exit())
+  }
+
+  private releasePrimary(): Promise<void> {
+    if (!this.primaryRelease) {
+      this.primaryRelease = this.runStage("primary release", () => this.dependencies.clientStateManager.drainAndReleasePrimary())
+    }
+    return this.primaryRelease
+  }
+
+  private async flushRenderer(window: BrowserWindow | null): Promise<void> {
+    const result = await flushRendererClientStateBeforeShutdown(
+      window,
+      this.dependencies.clientStateManager.isPrimary,
+      (url) => this.dependencies.isTrustedRendererOrigin(url, this.dependencies.getAllowedRendererOrigins(window)),
+      this.dependencies.rendererFlushTimeoutMs,
+    )
+    if (result === "untrusted-origin") {
+      console.warn("[client-state] skipped renderer flush for an untrusted origin")
+    }
+  }
+
+  private async flushNative(): Promise<void> {
+    if (this.windowStateTracker) await this.windowStateTracker.flush()
+    else await this.dependencies.clientStateManager.flush()
+  }
+
+  private async runStage(name: string, operation: () => Promise<unknown>): Promise<void> {
+    try {
+      await operation()
+    } catch (error) {
+      console.warn(`[client-state] ${name} failed; continuing`, error)
+    }
+  }
+
+  private exit(): void {
+    if (this.exitAllowed) return
+    this.exitAllowed = true
+    this.dependencies.app.exit(0)
+  }
+}
diff --git a/packages/electron-app/electron/main/client-state-navigation.test.ts b/packages/electron-app/electron/main/client-state-navigation.test.ts
new file mode 100644
index 00000000..8c40b0a9
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-navigation.test.ts
@@ -0,0 +1,89 @@
+import assert from "node:assert/strict"
+import { mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import test from "node:test"
+import { ClientStateManager } from "./client-state"
+import { ClientStateNavigationController, shouldResetRendererAccessTokenForNavigation } from "./client-state-navigation"
+
+const tick = () => new Promise((resolve) => setImmediate(resolve))
+function window(executeJavaScript: () => Promise<unknown> = async () => {}) {
+  return { isDestroyed: () => false, webContents: { isDestroyed: () => false, getURL: () => "http://127.0.0.1:3000/app", executeJavaScript } }
+}
+function controller(win: ReturnType<typeof window>, manager: { isPrimary: boolean }, report: (error: unknown) => void = (error) => assert.fail(String(error))) {
+  return new ClientStateNavigationController(win as never, { clientStateManager: manager, isTrustedOrigin: () => true, reportFlushError: report })
+}
+function managerHarness(t: test.TestContext) {
+  const directory = mkdtempSync(join(tmpdir(), "codenomad-navigation-"))
+  const manager = new ClientStateManager(directory, undefined, { crossHostElectionDirectory: join(directory, "election") })
+  t.after(async () => { await manager.drainAndReleasePrimary().catch(() => {}); rmSync(directory, { recursive: true, force: true }) })
+  return manager
+}
+
+test("renderer access resets only for trusted full main-frame navigation", () => {
+  const trusted = (url: string) => new URL(url).origin === "http://127.0.0.1:3000"
+  for (const [url, inPlace, mainFrame, expected] of [
+    ["http://127.0.0.1:3000/reload", false, true, true],
+    ["http://127.0.0.1:3000/frame", false, false, false],
+    ["http://127.0.0.1:3000/#route", true, true, false],
+    ["https://untrusted.example/reload", false, true, false],
+  ] as const) assert.equal(shouldResetRendererAccessTokenForNavigation(url, inPlace, mainFrame, trusted), expected)
+})
+
+test("immediate reload flushes latest state before rotating document access", async (t) => {
+  const manager = managerHarness(t)
+  await manager.setRestoreEnabled(true)
+  manager.claimClientStateAccess("outgoing")
+  const load = (token: string) => { manager.assertRendererAccessToken(token); return manager.loadClientState() }
+  const save = (token: string, state: unknown) => { manager.assertRendererAccessToken(token); return manager.saveClientState(state) }
+  for (const denied of [() => load("other"), () => save("other", {})]) assert.throws(denied, /has not been claimed/)
+  let navigated = false
+  await controller(window(() => save("outgoing", { revision: 7, editor: "latest" })), manager).navigate(() => {
+    navigated = true
+    assert.deepEqual(load("outgoing").snapshot, { revision: 7, editor: "latest" })
+    manager.resetRendererAccessToken()
+  })
+  assert.equal(navigated, true)
+  assert.throws(() => load("outgoing"), /has not been claimed/)
+  manager.claimClientStateAccess("incoming")
+  assert.deepEqual(load("incoming").snapshot, { revision: 7, editor: "latest" })
+})
+
+test("failed navigation retains current document access", async (t) => {
+  for (const [name, operation] of [
+    ["loadURL", () => Promise.reject(new Error("loadURL failed"))],
+    ["reload", () => { throw new Error("reload failed") }],
+  ] as const) await t.test(name, async (st) => {
+    const manager = managerHarness(st)
+    manager.claimClientStateAccess("current")
+    await assert.rejects(controller(window(), manager).navigate(operation), new RegExp(`${name} failed`))
+    manager.assertRendererAccessToken("current")
+    assert.equal(await manager.saveClientState({ retained: name }), true)
+  })
+})
+
+test("hung renderer flush is bounded without rotating access or blocking navigation", async () => {
+  const manager = { isPrimary: true, resets: 0, resetRendererAccessToken() { this.resets++ } }
+  let navigated = false, reported = false
+  const started = Date.now()
+  await controller(window(() => new Promise(() => {})), manager, () => { reported = true }).navigate(() => { navigated = true })
+  const elapsed = Date.now() - started
+  assert.equal(reported, true)
+  assert.equal(manager.resets, 0)
+  assert.equal(navigated, true)
+  assert.ok(elapsed >= 900 && elapsed < 2_000, `unexpected timeout: ${elapsed}ms`)
+})
+
+test("queued navigation preserves order and distinct generations", async () => {
+  const calls: string[] = []
+  let release!: () => void
+  const gate = new Promise<void>((resolve) => { release = resolve })
+  const navigation = controller(window(), { isPrimary: true })
+  const first = navigation.navigate(async (_window, generation) => { calls.push(`start-${generation}`); await gate; calls.push(`end-${generation}`) })
+  const second = navigation.navigate((_window, generation) => { calls.push(`run-${generation}`) })
+  await tick()
+  assert.deepEqual(calls, ["start-1"])
+  release()
+  await Promise.all([first, second])
+  assert.deepEqual(calls, ["start-1", "end-1", "run-2"])
+})
diff --git a/packages/electron-app/electron/main/client-state-navigation.ts b/packages/electron-app/electron/main/client-state-navigation.ts
new file mode 100644
index 00000000..feed061d
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-navigation.ts
@@ -0,0 +1,56 @@
+import type { BrowserWindow } from "electron"
+import type { ClientStateManager } from "./client-state"
+import { flushRendererClientStateBeforeShutdown } from "./renderer-client-state-flush"
+
+interface ClientStateNavigationDependencies {
+  clientStateManager: Pick<ClientStateManager, "isPrimary">
+  isTrustedOrigin(url: string): boolean
+  reportFlushError(error: unknown): void
+}
+
+export class ClientStateNavigationController {
+  private queue: Promise<void> = Promise.resolve()
+  private generation = 0
+
+  constructor(
+    private readonly window: BrowserWindow,
+    private readonly dependencies: ClientStateNavigationDependencies,
+  ) {}
+
+  navigate(operation: (window: BrowserWindow, generation: number) => void | Promise<void>): Promise<void> {
+    const generation = ++this.generation
+    const request = this.queue.catch(() => {}).then(() => this.performNavigation(operation, generation))
+    this.queue = request
+    return request
+  }
+
+  private async performNavigation(
+    operation: (window: BrowserWindow, generation: number) => void | Promise<void>,
+    generation: number,
+  ): Promise<void> {
+    const { window } = this
+    if (window.isDestroyed() || window.webContents.isDestroyed()) return
+
+    try {
+      await flushRendererClientStateBeforeShutdown(
+        window,
+        this.dependencies.clientStateManager.isPrimary,
+        this.dependencies.isTrustedOrigin,
+      )
+    } catch (error) {
+      this.dependencies.reportFlushError(error)
+    }
+
+    if (window.isDestroyed() || window.webContents.isDestroyed()) return
+    await operation(window, generation)
+  }
+}
+
+export function shouldResetRendererAccessTokenForNavigation(
+  url: string,
+  isInPlace: boolean,
+  isMainFrame: boolean,
+  isTrustedOrigin: (url: string) => boolean,
+): boolean {
+  return isMainFrame && !isInPlace && isTrustedOrigin(url)
+}
diff --git a/packages/electron-app/electron/main/client-state-process-identity.ts b/packages/electron-app/electron/main/client-state-process-identity.ts
new file mode 100644
index 00000000..749bfc57
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-process-identity.ts
@@ -0,0 +1,129 @@
+import { execFile, spawnSync } from "node:child_process"
+import { readFile as readFileAsync } from "node:fs/promises"
+import { readFileSync, readlinkSync } from "node:fs"
+import { basename, resolve } from "node:path"
+
+export type ProcessStartIdentityLookup = (pid: number) => string | undefined
+export type AsyncProcessStartIdentityLookup = (pid: number, timeoutMs: number) => Promise<string | undefined> | string | undefined
+export type ExpectedProcessLookup = (pid: number) => boolean | undefined
+
+function readLinuxProcessStartIdentity(pid: number): string | undefined {
+  const stat = readFileSync(`/proc/${pid}/stat`, "utf8")
+  const commandEnd = stat.lastIndexOf(")")
+  if (commandEnd < 0) return undefined
+
+  // Fields after the command begin with field 3; process start time is field 22.
+  const fields = stat.slice(commandEnd + 1).trim().split(/\s+/)
+  const startTicks = fields[19]
+  if (!startTicks) return undefined
+
+  const bootId = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()
+  return bootId ? `linux:${bootId}:${startTicks}` : undefined
+}
+
+function readCommandIdentity(command: string, args: string[], prefix: string): string | undefined {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const result = spawnSync(command, args, {
+      encoding: "utf8",
+      windowsHide: true,
+      timeout: 5_000,
+    })
+    if (result.status === 0 && !result.error) {
+      const value = result.stdout.trim()
+      if (value) return `${prefix}:${value}`
+    }
+  }
+  return undefined
+}
+
+function readCommandIdentityAsync(command: string, args: string[], prefix: string, timeoutMs: number): Promise<string | undefined> {
+  if (timeoutMs <= 0) return Promise.resolve(undefined)
+  return new Promise((resolve) => {
+    execFile(command, args, { encoding: "utf8", windowsHide: true, timeout: timeoutMs }, (error, stdout) => {
+      const value = error ? "" : stdout.trim()
+      resolve(value ? `${prefix}:${value}` : undefined)
+    })
+  })
+}
+
+export function getProcessStartIdentity(pid: number): string | undefined {
+  if (!Number.isInteger(pid) || pid <= 0) return undefined
+
+  try {
+    if (process.platform === "linux") {
+      return readLinuxProcessStartIdentity(pid)
+    }
+    if (process.platform === "darwin") {
+      return readCommandIdentity("ps", ["-p", String(pid), "-o", "lstart="], "darwin")
+    }
+    if (process.platform === "win32") {
+      return readCommandIdentity(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}" -ErrorAction Stop).CreationDate.ToUniversalTime().Ticks`,
+        ],
+        "win32",
+      )
+    }
+  } catch {
+    // Identity lookup is best-effort; callers preserve election safety when it is unavailable.
+  }
+
+  return undefined
+}
+
+export async function getProcessStartIdentityAsync(
+  pid: number,
+  timeoutMs: number,
+  platform: NodeJS.Platform = process.platform,
+): Promise<string | undefined> {
+  if (!Number.isInteger(pid) || pid <= 0 || timeoutMs <= 0) return undefined
+  try {
+    if (platform === "linux") {
+      const signal = AbortSignal.timeout(timeoutMs)
+      const stat = await readFileAsync(`/proc/${pid}/stat`, { encoding: "utf8", signal })
+      const commandEnd = stat.lastIndexOf(")")
+      const startTicks = commandEnd < 0 ? undefined : stat.slice(commandEnd + 1).trim().split(/\s+/)[19]
+      if (!startTicks) return undefined
+      const bootId = (await readFileAsync("/proc/sys/kernel/random/boot_id", { encoding: "utf8", signal })).trim()
+      return bootId ? `linux:${bootId}:${startTicks}` : undefined
+    }
+    if (platform === "darwin") {
+      return readCommandIdentityAsync("ps", ["-p", String(pid), "-o", "lstart="], "darwin", timeoutMs)
+    }
+    if (platform === "win32") {
+      return readCommandIdentityAsync("powershell.exe", [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}" -ErrorAction Stop).CreationDate.ToUniversalTime().Ticks`,
+      ], "win32", timeoutMs)
+    }
+  } catch {
+    // Identity lookup is best-effort; callers refuse destructive actions when it is unavailable.
+  }
+  return undefined
+}
+
+export function isExpectedTauriProcess(pid: number): boolean | undefined {
+  try {
+    const executable = process.platform === "linux"
+      ? readlinkSync(`/proc/${pid}/exe`)
+      : readCommandIdentity(
+          process.platform === "win32" ? "powershell.exe" : "ps",
+          process.platform === "win32"
+            ? ["-NoProfile", "-NonInteractive", "-Command", `(Get-Process -Id ${pid} -ErrorAction Stop).Path`]
+            : ["-p", String(pid), "-o", "comm="],
+          "path",
+        )?.slice(5)
+    if (!executable) return undefined
+    if (resolve(executable).toLowerCase() === resolve(process.execPath).toLowerCase()) return false
+    return ["codenomad", "codenomad.exe", "codenomad-tauri", "codenomad-tauri.exe"]
+      .includes(basename(executable).toLowerCase())
+  } catch {
+    return undefined
+  }
+}
diff --git a/packages/electron-app/electron/main/client-state-process.test.ts b/packages/electron-app/electron/main/client-state-process.test.ts
new file mode 100644
index 00000000..fe9e0bde
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-process.test.ts
@@ -0,0 +1,190 @@
+import assert from "node:assert/strict"
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"
+import { randomUUID } from "node:crypto"
+import { once } from "node:events"
+import fs, { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { syncBuiltinESMExports } from "node:module"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+import test from "node:test"
+import { cleanStaleRunningMarkers, createRunningMarker, electClientStateProcess, getRunningMarkerPath, hasLiveTauriClient, REGISTRATION_LOCK_WAIT_MS, removeProcessOwnerLockIfOwned, removeRunningMarkerIfOwned, type ProcessOwner } from "./client-state-process"
+import { getProcessStartIdentity, getProcessStartIdentityAsync } from "./client-state-process-identity"
+
+function temp(t: test.TestContext) { const directory = mkdtempSync(join(tmpdir(), "codenomad-election-")); t.after(() => rmSync(directory, { recursive: true, force: true })); return directory }
+
+test("legacy Tauri markers block only while their PID may be live", (t) => {
+  const directory = temp(t)
+  writeFileSync(join(directory, "client-state.running.123.1.lock"), "")
+  writeFileSync(join(directory, "client-state.running.456.2.lock"), "")
+  assert.equal(hasLiveTauriClient(directory, (pid) => pid === 456), true)
+  assert.equal(hasLiveTauriClient(directory, () => false), false)
+  assert.equal(hasLiveTauriClient(directory, (pid) => pid === 456, () => "reused", () => false), false)
+  assert.equal(hasLiveTauriClient(directory, (pid) => pid === 456, () => undefined, () => undefined), true)
+  assert.equal(hasLiveTauriClient(directory, (pid) => pid === 456, () => "tauri-start", () => true), true)
+  assert.equal(hasLiveTauriClient(directory, (pid) => pid === 456, () => "tauri-start", () => true, [
+    { pid: 456, runToken: "upgraded", processStartIdentity: "tauri-start" },
+  ]), false)
+})
+
+interface Child { process: ChildProcessWithoutNullStreams; result: Promise<{ isPrimary: boolean }> }
+function child(directory: string, start: string, wait = "", paused = "", release = ""): Child {
+  const process = spawn(globalThis.process.execPath, ["--import", "tsx", fileURLToPath(new URL("./client-state-election-child.ts", import.meta.url)), directory, randomUUID(), start, wait, paused, release])
+  process.stdout.setEncoding("utf8"); process.stderr.setEncoding("utf8")
+  const result = new Promise<{ isPrimary: boolean }>((resolve, reject) => {
+    let output = "", errors = "", settled = false
+    process.stdout.on("data", (chunk: string) => {
+      output += chunk
+      const end = output.indexOf("\n")
+      if (end >= 0 && !settled) { settled = true; resolve(JSON.parse(output.slice(0, end))) }
+    })
+    process.stderr.on("data", (chunk: string) => { errors += chunk }); process.once("error", reject)
+    process.once("exit", (code) => { if (!settled) reject(new Error(`child ${code}: ${errors}`)) })
+  })
+  return { process, result }
+}
+async function stop(children: Child[]) { const exits = children.map(({ process }) => once(process, "exit")); children.forEach(({ process }) => process.stdin.end()); await Promise.all(exits) }
+async function contenders(directory: string, configure?: () => void, count = 2) {
+  const start = join(directory, "start")
+  configure?.()
+  const children = Array.from({ length: count }, () => child(directory, start, "40"))
+  try {
+    writeFileSync(start, "")
+    const roles = await Promise.all(children.map(({ result }) => result))
+    assert.equal(roles.filter(({ isPrimary }) => isPrimary).length, 1, JSON.stringify(roles))
+  } finally { await stop(children) }
+}
+
+test("current process start identity is stable", () => {
+  const identity = getProcessStartIdentity(process.pid)
+  assert.ok(identity, `identity unavailable on ${process.platform}`)
+  assert.equal(getProcessStartIdentity(process.pid), identity)
+})
+
+test("async process identity matches the spawn-time identity", async () => {
+  const identity = getProcessStartIdentity(process.pid)
+  assert.ok(identity)
+  assert.equal(await getProcessStartIdentityAsync(process.pid, 1_500), identity)
+})
+
+test("marker cleanup preserves only election-relevant live cohorts", async (t) => {
+  const cases: Array<{ name: string; marker: ProcessOwner; current: ProcessOwner; alive: boolean; identity?: string; primary?: ProcessOwner; blocking: boolean; remains: boolean }> = [
+    { name: "live secondary", marker: { pid: 2, runToken: "live" }, current: { pid: 3, runToken: "new" }, alive: true, blocking: true, remains: true },
+    { name: "same PID old run", marker: { pid: 4, runToken: "old" }, current: { pid: 4, runToken: "new" }, alive: true, blocking: false, remains: false },
+    { name: "reused PID", marker: { pid: 5, runToken: "old", processStartIdentity: "old" }, current: { pid: 6, runToken: "new" }, alive: true, identity: "reused", blocking: false, remains: false },
+    { name: "unknown identity", marker: { pid: 7, runToken: "unknown", processStartIdentity: "old" }, current: { pid: 8, runToken: "new" }, alive: true, blocking: true, remains: true },
+    { name: "acknowledged primary", marker: { pid: 9, runToken: "secondary" }, current: { pid: 10, runToken: "primary" }, alive: true, primary: { pid: 10, runToken: "primary" }, blocking: false, remains: true },
+  ]
+  for (const value of cases) await t.test(value.name, (st) => {
+    const directory = temp(st)
+    const path = createRunningMarker(directory, value.marker, value.primary)
+    const identity = () => value.identity
+    assert.equal(cleanStaleRunningMarkers(directory, value.current, () => value.alive, identity), value.blocking)
+    assert.equal(existsSync(path), value.remains)
+  })
+})
+
+test("marker removal and mismatched contents never discard a possible live owner", (t) => {
+  const directory = temp(t)
+  const filenameOwner = { pid: 11, runToken: "filename" }
+  const storedOwner = { pid: 12, runToken: "stored" }
+  const current = { pid: 13, runToken: "current" }
+  const path = createRunningMarker(directory, filenameOwner)
+  writeFileSync(path, JSON.stringify(storedOwner))
+  assert.equal(removeRunningMarkerIfOwned(path, filenameOwner), false)
+  assert.deepEqual(JSON.parse(readFileSync(path, "utf8")), storedOwner)
+  assert.equal(cleanStaleRunningMarkers(directory, current, () => false), false)
+  assert.equal(existsSync(path), false)
+  createRunningMarker(directory, filenameOwner)
+  writeFileSync(path, JSON.stringify(storedOwner))
+  assert.equal(cleanStaleRunningMarkers(directory, current, (pid) => pid === filenameOwner.pid), true)
+  assert.equal(existsSync(path), true)
+})
+
+test("process files tolerate only unsupported fsync and never clobber an owner", (t) => {
+  const directory = temp(t)
+  const first = { pid: 14, runToken: "first" }
+  const path = createRunningMarker(directory, first)
+  assert.throws(() => createRunningMarker(directory, { pid: 14, runToken: "first" }), { code: "EEXIST" })
+  assert.deepEqual(JSON.parse(readFileSync(path, "utf8")), first)
+  const original = fs.fsyncSync
+  t.after(() => { fs.fsyncSync = original; syncBuiltinESMExports() })
+  for (const [code, retained] of [["EINVAL", true], ["ENOTSUP", true], ["ENOSYS", true], ["EIO", false]] as const) {
+    fs.fsyncSync = () => { throw Object.assign(new Error(code), { code }) }; syncBuiltinESMExports()
+    const owner = { pid: 15, runToken: code }, next = getRunningMarkerPath(directory, owner)
+    if (retained) createRunningMarker(directory, owner)
+    else assert.throws(() => createRunningMarker(directory, owner), { code })
+    assert.equal(existsSync(next), retained)
+  }
+})
+
+test("simultaneous registration and stale lock recovery elect exactly one primary", async (t) => {
+  await t.test("clean", (st) => contenders(temp(st)))
+  await t.test("unrelated live registration PID", (st) => {
+    const directory = temp(st)
+    return contenders(directory, () => writeFileSync(join(directory, "client-state.registration.lock"), JSON.stringify({ pid: process.pid, runToken: "old" })))
+  })
+  for (let round = 0; round < 10; round++) await t.test(`reused primary PID ${round}`, (st) => {
+    const directory = temp(st)
+    return contenders(directory, () => {
+      const owner = { pid: process.pid, runToken: `old-${round}`, processStartIdentity: `old-start-${round}` }
+      writeFileSync(join(directory, "client-state.primary.lock"), JSON.stringify(owner))
+      createRunningMarker(directory, owner)
+    })
+  })
+})
+
+test("overlapping stale-registration recovery cannot leave all contenders secondary", async (t) => {
+  const directory = temp(t), start = join(directory, "start"), paused = join(directory, "paused"), release = join(directory, "release")
+  writeFileSync(join(directory, "client-state.registration.lock"), JSON.stringify({ pid: process.pid, runToken: "old" }))
+  const children = [child(directory, start, "40", paused, release), child(directory, start, "40", paused, release)]
+  try {
+    writeFileSync(start, "")
+    const deadline = Date.now() + 2_000
+    while (!existsSync(paused) && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 5))
+    assert.equal(existsSync(paused), true)
+    await Promise.race(children.map(({ result }) => result))
+    writeFileSync(release, "")
+    const roles = await Promise.all(children.map(({ result }) => result))
+    assert.equal(roles.filter(({ isPrimary }) => isPrimary).length, 1, JSON.stringify(roles))
+  } finally { if (!existsSync(release)) writeFileSync(release, ""); await stop(children) }
+})
+
+test("a surviving older secondary keeps later processes secondary", async (t) => {
+  const directory = temp(t)
+  const launch = async (name: string) => {
+    const start = join(directory, name), next = child(directory, start)
+    writeFileSync(start, "")
+    return { next, role: await next.result }
+  }
+  const first = await launch("first"); assert.equal(first.role.isPrimary, true)
+  const second = await launch("second"); assert.equal(second.role.isPrimary, false)
+  await stop([first.next])
+  const third = await launch("third")
+  await stop([second.next, third.next])
+  assert.equal(third.role.isPrimary, false)
+})
+
+test("lock recovery handles PID reuse, malformed files, and verified live owners", async (t) => {
+  const cases = [
+    { name: "same PID old token", owner: { pid: process.pid, runToken: "new" }, file: { pid: process.pid, runToken: "old" }, lock: "primary", alive: () => true, expected: true },
+    { name: "malformed registration", owner: { pid: 21, runToken: "new" }, file: "malformed", lock: "registration", alive: () => true, expected: false },
+    { name: "live registration marker", owner: { pid: 22, runToken: "new" }, file: { pid: 23, runToken: "live" }, lock: "registration", alive: (pid: number) => pid === 23, marker: true, expected: false },
+    { name: "identity-verified registration", owner: { pid: 24, runToken: "new" }, file: { pid: 25, runToken: "live", processStartIdentity: "start" }, lock: "registration", alive: (pid: number) => pid === 25, identity: () => "start", expected: false },
+    { name: "live primary marker", owner: { pid: 26, runToken: "new" }, file: { pid: 27, runToken: "live" }, lock: "primary", alive: (pid: number) => pid === 27, marker: true, expected: false },
+  ] as const
+  for (const value of cases) await t.test(value.name, (st) => {
+    const directory = temp(st), primary = join(directory, "client-state.primary.lock"), registration = join(directory, "client-state.registration.lock")
+    const path = value.lock === "primary" ? primary : registration
+    writeFileSync(path, typeof value.file === "string" ? value.file : JSON.stringify(value.file))
+    if ("marker" in value && value.marker && typeof value.file !== "string") createRunningMarker(directory, value.file)
+    const started = Date.now()
+    const elected = electClientStateProcess(directory, value.owner, { primaryLockPath: primary, registrationLockPath: registration }, () => {}, value.alive, 30, () => {}, "identity" in value ? value.identity : undefined)
+    assert.equal(elected, value.expected)
+    assert.ok(Date.now() - started < 500)
+    if (!value.expected) assert.deepEqual(readFileSync(path, "utf8"), typeof value.file === "string" ? value.file : JSON.stringify(value.file))
+    removeRunningMarkerIfOwned(getRunningMarkerPath(directory, value.owner), value.owner)
+    removeProcessOwnerLockIfOwned(primary, value.owner)
+  })
+  assert.equal(REGISTRATION_LOCK_WAIT_MS, 1_000)
+})
diff --git a/packages/electron-app/electron/main/client-state-process.ts b/packages/electron-app/electron/main/client-state-process.ts
new file mode 100644
index 00000000..6874dde0
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state-process.ts
@@ -0,0 +1,511 @@
+import { closeSync, fsyncSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs"
+import { basename, join } from "node:path"
+import {
+  type ExpectedProcessLookup,
+  getProcessStartIdentity,
+  isExpectedTauriProcess,
+  type ProcessStartIdentityLookup,
+} from "./client-state-process-identity"
+
+const RUNNING_MARKER_PREFIX = "client-state.running."
+const RUNNING_MARKER_SUFFIX = ".json"
+const PRIMARY_LOCK_ACQUIRE_ATTEMPTS = 5
+const LOCK_RETRY_DELAY_MS = 10
+export const REGISTRATION_LOCK_WAIT_MS = 1_000
+
+export interface ProcessOwner {
+  pid: number
+  runToken: string
+  processStartIdentity?: string
+}
+
+export type RunningMarkerStatus = "current" | "other-live" | "stale"
+
+export interface ClientStateElectionPaths {
+  primaryLockPath: string
+  registrationLockPath: string
+}
+
+interface ProcessOwnerLockAcquisition {
+  acquired: boolean
+  liveOwner?: {
+    owner: ProcessOwner
+    observed: string
+  }
+}
+
+export function hasErrorCode(error: unknown, code: string): boolean {
+  return error instanceof Error && "code" in error && error.code === code
+}
+
+function isTransientFileContentionError(error: unknown): boolean {
+  return hasErrorCode(error, "EPERM") || hasErrorCode(error, "EACCES") || hasErrorCode(error, "EBUSY")
+}
+
+export function parseProcessOwner(value: string): ProcessOwner | undefined {
+  try {
+    return normalizeProcessOwner(JSON.parse(value))
+  } catch {
+    // Incomplete process files are handled conservatively using their filename owner.
+  }
+  return undefined
+}
+
+function normalizeProcessOwner(candidate: unknown): ProcessOwner | undefined {
+  if (!candidate || typeof candidate !== "object") {
+    return undefined
+  }
+  const owner = candidate as Partial<ProcessOwner>
+  if (Number.isInteger(owner.pid) && Number(owner.pid) > 0 && typeof owner.runToken === "string" && owner.runToken) {
+    return {
+      pid: Number(owner.pid),
+      runToken: owner.runToken,
+      ...(typeof owner.processStartIdentity === "string" && owner.processStartIdentity
+        ? { processStartIdentity: owner.processStartIdentity }
+        : {}),
+    }
+  }
+  return undefined
+}
+
+function parseAcknowledgedPrimary(value: string): ProcessOwner | undefined {
+  try {
+    const candidate = JSON.parse(value) as { primaryOwner?: unknown }
+    return normalizeProcessOwner(candidate.primaryOwner)
+  } catch {
+    return undefined
+  }
+}
+
+export function isSameProcessOwner(left: ProcessOwner, right: ProcessOwner): boolean {
+  return left.pid === right.pid && left.runToken === right.runToken
+}
+
+export function isPidAlive(pid: number): boolean {
+  if (pid === process.pid) {
+    return true
+  }
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return !hasErrorCode(error, "ESRCH")
+  }
+}
+
+export function hasLiveTauriClient(
+  tauriDataPath: string,
+  pidAlive: (pid: number) => boolean = isPidAlive,
+  processStartIdentity: ProcessStartIdentityLookup = getProcessStartIdentity,
+  expectedProcess: ExpectedProcessLookup = isExpectedTauriProcess,
+  upgradedParticipants: readonly ProcessOwner[] = [],
+): boolean {
+  let entries: string[]
+  try {
+    entries = readdirSync(tauriDataPath)
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) return false
+    throw error
+  }
+  return entries.some((name) => {
+    const match = /^client-state\.running\.(\d+)\..+\.lock$/.exec(name)
+    if (!match) return false
+    const pid = Number(match[1])
+    if (!Number.isInteger(pid) || pid <= 0 || !pidAlive(pid)) return false
+    const liveIdentity = processStartIdentity(pid)
+    if (liveIdentity && upgradedParticipants.some((owner) => owner.pid === pid && owner.processStartIdentity === liveIdentity)) return false
+    return expectedProcess(pid) !== false
+  })
+}
+
+export function classifyRunningMarker(
+  markerOwner: ProcessOwner,
+  currentOwner: ProcessOwner,
+  pidAlive: (pid: number) => boolean = isPidAlive,
+  processStartIdentity: ProcessStartIdentityLookup = getProcessStartIdentity,
+): RunningMarkerStatus {
+  if (isSameProcessOwner(markerOwner, currentOwner)) {
+    return "current"
+  }
+  // Two live processes cannot share a PID. A different token therefore belongs to an old run.
+  if (markerOwner.pid === currentOwner.pid) {
+    return "stale"
+  }
+  if (!pidAlive(markerOwner.pid)) return "stale"
+  if (markerOwner.processStartIdentity) {
+    const liveIdentity = processStartIdentity(markerOwner.pid)
+    if (liveIdentity && liveIdentity !== markerOwner.processStartIdentity) return "stale"
+  }
+  return "other-live"
+}
+
+export function getRunningMarkerPath(userDataPath: string, owner: ProcessOwner): string {
+  return join(userDataPath, `${RUNNING_MARKER_PREFIX}${owner.pid}.${owner.runToken}${RUNNING_MARKER_SUFFIX}`)
+}
+
+function parseRunningMarkerFilename(filename: string): ProcessOwner | undefined {
+  if (!filename.startsWith(RUNNING_MARKER_PREFIX) || !filename.endsWith(RUNNING_MARKER_SUFFIX)) {
+    return undefined
+  }
+
+  const value = filename.slice(RUNNING_MARKER_PREFIX.length, -RUNNING_MARKER_SUFFIX.length)
+  const separator = value.indexOf(".")
+  if (separator < 1) {
+    return undefined
+  }
+  const pid = Number(value.slice(0, separator))
+  const runToken = value.slice(separator + 1)
+  if (!Number.isInteger(pid) || pid <= 0 || !runToken) {
+    return undefined
+  }
+  return { pid, runToken }
+}
+
+export function createRunningMarker(
+  userDataPath: string,
+  owner: ProcessOwner,
+  primaryOwner?: ProcessOwner,
+): string {
+  const markerPath = getRunningMarkerPath(userDataPath, owner)
+  publishProcessFile(markerPath, JSON.stringify(primaryOwner ? { ...owner, primaryOwner } : owner))
+  return markerPath
+}
+
+function publishProcessFile(path: string, contents: string): void {
+  let descriptor: number | undefined
+  try {
+    descriptor = openSync(path, "wx", 0o600)
+    writeFileSync(descriptor, contents, "utf8")
+    try {
+      fsyncSync(descriptor)
+    } catch (error) {
+      if (!["EINVAL", "ENOTSUP", "ENOSYS"].some((code) => hasErrorCode(error, code))) throw error
+    }
+    closeSync(descriptor)
+    descriptor = undefined
+  } catch (error) {
+    if (descriptor !== undefined) {
+      try { closeSync(descriptor) } catch {}
+      try { unlinkSync(path) } catch {}
+    }
+    throw error
+  }
+}
+
+function removeFileIfUnchanged(path: string, observed: string): boolean {
+  try {
+    if (readFileSync(path, "utf8") !== observed) {
+      return false
+    }
+    unlinkSync(path)
+    return true
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) {
+      return false
+    }
+    throw error
+  }
+}
+
+function readFileIfExists(path: string): string | undefined {
+  try {
+    return readFileSync(path, "utf8")
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) return undefined
+    throw error
+  }
+}
+
+function waitForLockRetry(delayMs = LOCK_RETRY_DELAY_MS) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, delayMs))
+}
+
+function removeContendedFile(path: string, observed: string): void {
+  try {
+    removeFileIfUnchanged(path, observed)
+  } catch (error) {
+    if (!isTransientFileContentionError(error)) throw error
+    waitForLockRetry()
+  }
+}
+
+function acquireProcessOwnerLockWithStatus(
+  path: string,
+  owner: ProcessOwner,
+  waitForLiveOwner: boolean,
+  pidAlive: (pid: number) => boolean = isPidAlive,
+  liveOwnerWaitMs = REGISTRATION_LOCK_WAIT_MS,
+  processStartIdentity: ProcessStartIdentityLookup = getProcessStartIdentity,
+): ProcessOwnerLockAcquisition {
+  const serializedOwner = JSON.stringify(owner)
+  const waitDeadline = Date.now() + Math.max(0, liveOwnerWaitMs)
+  let liveOwner: ProcessOwnerLockAcquisition["liveOwner"]
+
+  for (let attempt = 0; ; attempt += 1) {
+    if (
+      (!waitForLiveOwner && attempt >= PRIMARY_LOCK_ACQUIRE_ATTEMPTS) ||
+      (waitForLiveOwner && attempt > 0 && Date.now() >= waitDeadline)
+    ) {
+      return { acquired: false, liveOwner }
+    }
+
+    try {
+      publishProcessFile(path, serializedOwner)
+      return { acquired: true }
+    } catch (error) {
+      if (!hasErrorCode(error, "EEXIST")) {
+        throw error
+      }
+    }
+
+    const observed = readFileIfExists(path)
+    if (observed === undefined) continue
+
+    const existingOwner = parseProcessOwner(observed)
+    if (existingOwner) {
+      const status = classifyRunningMarker(existingOwner, owner, pidAlive, processStartIdentity)
+      if (status === "other-live") {
+        liveOwner = { owner: existingOwner, observed }
+        if (!waitForLiveOwner) {
+          return { acquired: false, liveOwner }
+        }
+        const remainingWaitMs = waitDeadline - Date.now()
+        if (remainingWaitMs <= 0) {
+          return { acquired: false, liveOwner }
+        }
+        waitForLockRetry(Math.min(LOCK_RETRY_DELAY_MS, remainingWaitMs))
+        continue
+      }
+    } else if (waitForLiveOwner && attempt < PRIMARY_LOCK_ACQUIRE_ATTEMPTS - 1) {
+      // The owner may still be writing a newly-created lock file.
+      waitForLockRetry()
+      continue
+    }
+
+    removeContendedFile(path, observed)
+  }
+
+  return { acquired: false, liveOwner }
+}
+
+export function removeProcessOwnerLockIfOwned(path: string, owner: ProcessOwner): boolean {
+  const observed = readFileIfExists(path)
+  const current = observed === undefined ? undefined : parseProcessOwner(observed)
+  return Boolean(current && isSameProcessOwner(current, owner) && removeFileIfUnchanged(path, observed!))
+}
+
+function releaseProcessOwnerLock(
+  path: string,
+  owner: ProcessOwner,
+  onWarning: (message: string, error: unknown) => void,
+  warning: string,
+): void {
+  try {
+    removeProcessOwnerLockIfOwned(path, owner)
+  } catch (error) {
+    onWarning(warning, error)
+  }
+}
+
+export function isProcessOwnerLockOwned(path: string, owner: ProcessOwner): boolean {
+  const value = readFileIfExists(path)
+  const current = value === undefined ? undefined : parseProcessOwner(value)
+  return Boolean(current && isSameProcessOwner(current, owner))
+}
+
+export function removeRunningMarkerIfOwned(markerPath: string, owner: ProcessOwner): boolean {
+  const filenameOwner = parseRunningMarkerFilename(basename(markerPath))
+  if (!filenameOwner || !isSameProcessOwner(filenameOwner, owner)) {
+    return false
+  }
+
+  const observed = readFileIfExists(markerPath)
+  const storedOwner = observed === undefined ? undefined : parseProcessOwner(observed)
+  return Boolean(storedOwner && isSameProcessOwner(storedOwner, owner) && removeFileIfUnchanged(markerPath, observed!))
+}
+
+export function cleanStaleRunningMarkers(
+  userDataPath: string,
+  currentOwner: ProcessOwner,
+  pidAlive: (pid: number) => boolean = isPidAlive,
+  processStartIdentity: ProcessStartIdentityLookup = getProcessStartIdentity,
+): boolean {
+  let hasOtherLiveProcess = false
+
+  for (const filename of readdirSync(userDataPath)) {
+    const filenameOwner = parseRunningMarkerFilename(filename)
+    if (!filenameOwner) {
+      continue
+    }
+
+    const markerPath = join(userDataPath, filename)
+    const observed = readFileIfExists(markerPath)
+    if (observed === undefined) continue
+
+    const storedOwner = parseProcessOwner(observed)
+    if (storedOwner && !isSameProcessOwner(storedOwner, filenameOwner)) {
+      const storedStatus = classifyRunningMarker(storedOwner, currentOwner, pidAlive, processStartIdentity)
+      const filenameStatus = classifyRunningMarker(filenameOwner, currentOwner, pidAlive, processStartIdentity)
+      if (storedStatus === "other-live" || filenameStatus === "other-live") {
+        hasOtherLiveProcess = true
+      } else {
+        removeFileIfUnchanged(markerPath, observed)
+      }
+      continue
+    }
+
+    const markerOwner = storedOwner ?? filenameOwner
+    const status = classifyRunningMarker(markerOwner, currentOwner, pidAlive, processStartIdentity)
+    if (status === "other-live") {
+      const acknowledgedPrimary = parseAcknowledgedPrimary(observed)
+      if (!acknowledgedPrimary || !isSameProcessOwner(acknowledgedPrimary, currentOwner)) {
+        hasOtherLiveProcess = true
+      }
+    } else if (status === "stale") {
+      removeFileIfUnchanged(markerPath, observed)
+    }
+  }
+
+  return hasOtherLiveProcess
+}
+
+function hasMatchingLiveRunningMarker(
+  userDataPath: string,
+  owner: ProcessOwner,
+  pidAlive: (pid: number) => boolean,
+  processStartIdentity: ProcessStartIdentityLookup,
+): boolean {
+  if (!pidAlive(owner.pid)) {
+    return false
+  }
+
+  const value = readFileIfExists(getRunningMarkerPath(userDataPath, owner))
+  const markerOwner = value === undefined ? undefined : parseProcessOwner(value)
+  if (!markerOwner || !isSameProcessOwner(markerOwner, owner)) return false
+  const liveIdentity = markerOwner.processStartIdentity && processStartIdentity(markerOwner.pid)
+  return !liveIdentity || liveIdentity === markerOwner.processStartIdentity
+}
+
+function acquireMarkerBackedProcessOwnerLock(
+  userDataPath: string,
+  path: string,
+  owner: ProcessOwner,
+  pidAlive: (pid: number) => boolean,
+  liveOwnerWaitMs: number,
+  processStartIdentity: ProcessStartIdentityLookup,
+): ProcessOwnerLockAcquisition {
+  let lastAcquisition: ProcessOwnerLockAcquisition = { acquired: false }
+  for (let recoveryAttempt = 0; recoveryAttempt < PRIMARY_LOCK_ACQUIRE_ATTEMPTS; recoveryAttempt += 1) {
+    const acquisition = acquireProcessOwnerLockWithStatus(
+      path,
+      owner,
+      true,
+      pidAlive,
+      liveOwnerWaitMs,
+      processStartIdentity,
+    )
+    lastAcquisition = acquisition
+    if (acquisition.acquired || !acquisition.liveOwner) {
+      if (acquisition.acquired) return acquisition
+      continue
+    }
+    // An identity-backed owner only reaches this point after an exact identity match
+    // or an inconclusive lookup. Never steal its lock while its PID remains live.
+    if (acquisition.liveOwner.owner.processStartIdentity) {
+      return acquisition
+    }
+    if (hasMatchingLiveRunningMarker(
+      userDataPath,
+      acquisition.liveOwner.owner,
+      pidAlive,
+      processStartIdentity,
+    )) {
+      return acquisition
+    }
+    removeContendedFile(path, acquisition.liveOwner.observed)
+  }
+  return lastAcquisition
+}
+
+export function electClientStateProcess(
+  userDataPath: string,
+  owner: ProcessOwner,
+  paths: ClientStateElectionPaths,
+  onWarning: (message: string, error: unknown) => void = () => {},
+  pidAlive: (pid: number) => boolean = isPidAlive,
+  registrationLockWaitMs = REGISTRATION_LOCK_WAIT_MS,
+  onPrimaryLockAcquired: () => void = () => {},
+  processStartIdentity: ProcessStartIdentityLookup = getProcessStartIdentity,
+): boolean {
+  let registrationAcquired = false
+  let registeringOwner: ProcessOwner | undefined
+
+  try {
+    const registration = acquireMarkerBackedProcessOwnerLock(
+      userDataPath,
+      paths.registrationLockPath,
+      owner,
+      pidAlive,
+      registrationLockWaitMs,
+      processStartIdentity,
+    )
+    registrationAcquired = registration.acquired
+    registeringOwner = registration.liveOwner?.owner
+  } catch (error) {
+    onWarning("failed to acquire registration lock", error)
+  }
+
+  if (!registrationAcquired) {
+    try {
+      createRunningMarker(userDataPath, owner, registeringOwner)
+    } catch (error) {
+      onWarning("failed to create running marker", error)
+    }
+    return false
+  }
+
+  try {
+    let isPrimary = false
+    let acknowledgedPrimary: ProcessOwner | undefined
+    try {
+      const acquisition = acquireMarkerBackedProcessOwnerLock(
+        userDataPath,
+        paths.primaryLockPath,
+        owner,
+        pidAlive,
+        registrationLockWaitMs,
+        processStartIdentity,
+      )
+      isPrimary = acquisition.acquired
+      acknowledgedPrimary = acquisition.liveOwner?.owner
+    } catch (error) {
+      onWarning("failed to acquire primary lock", error)
+    }
+
+    if (isPrimary) {
+      try {
+        onPrimaryLockAcquired()
+        if (cleanStaleRunningMarkers(userDataPath, owner, pidAlive, processStartIdentity)) {
+          removeProcessOwnerLockIfOwned(paths.primaryLockPath, owner)
+          isPrimary = false
+        }
+      } catch (error) {
+        onWarning("failed to inspect running markers", error)
+        releaseProcessOwnerLock(paths.primaryLockPath, owner, onWarning, "failed to release primary lock")
+        isPrimary = false
+      }
+    }
+
+    try {
+      createRunningMarker(userDataPath, owner, acknowledgedPrimary)
+    } catch (error) {
+      onWarning("failed to create running marker", error)
+      if (isPrimary) releaseProcessOwnerLock(paths.primaryLockPath, owner, onWarning, "failed to release primary lock")
+      return false
+    }
+
+    return isPrimary
+  } finally {
+    releaseProcessOwnerLock(paths.registrationLockPath, owner, onWarning, "failed to release registration lock")
+  }
+}
diff --git a/packages/electron-app/electron/main/client-state.test.ts b/packages/electron-app/electron/main/client-state.test.ts
new file mode 100644
index 00000000..18ee8d3a
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state.test.ts
@@ -0,0 +1,282 @@
+import assert from "node:assert/strict"
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import test from "node:test"
+import { ClientStateManager, type ClientStateWriter } from "./client-state"
+
+function harness(t: test.TestContext, initial?: object) {
+  const directory = mkdtempSync(join(tmpdir(), "codenomad-state-"))
+  const statePath = join(directory, "client-state.json")
+  if (initial) writeFileSync(statePath, JSON.stringify(initial))
+  let failing = false
+  let writes = 0
+  const managers: ClientStateManager[] = []
+  const create = (writer: ClientStateWriter = async (path, value) => {
+    writes++
+    if (failing) throw new Error("injected write failure")
+    await writeFile(path, value, "utf8")
+  }, processOwner?: { pid: number; runToken: string; processStartIdentity: string }) => {
+    const manager = new ClientStateManager(directory, writer, { crossHostElectionDirectory: join(directory, "election"), processOwner })
+    managers.push(manager)
+    return manager
+  }
+  t.after(async () => {
+    await Promise.all(managers.map((manager) => manager.drainAndReleasePrimary().catch(() => {})))
+    rmSync(directory, { recursive: true, force: true })
+  })
+  return { create, directory, statePath, fail: (value: boolean) => { failing = value }, writes: () => writes }
+}
+
+test("renderer access is exclusive per document and resettable", async (t) => {
+  const manager = harness(t, { version: 1, restoreEnabled: true }).create()
+  assert.throws(() => manager.claimClientStateAccess(""), /nonempty string/)
+  assert.throws(() => manager.assertRendererAccessToken("unclaimed"), /has not been claimed/)
+  assert.equal(manager.claimClientStateAccess("document-1"), true)
+  assert.equal(manager.claimClientStateAccess("document-1"), true)
+  assert.throws(() => manager.claimClientStateAccess("document-2"), /does not match/)
+  manager.assertRendererAccessToken("document-1")
+  assert.equal(await manager.saveClientState({ saved: true }), true)
+  manager.resetRendererAccessToken()
+  assert.throws(() => manager.assertRendererAccessToken("document-1"), /has not been claimed/)
+  assert.equal(manager.claimClientStateAccess("document-2"), true)
+})
+
+test("restore defaults on unless explicitly disabled", (t) => {
+  assert.equal(harness(t).create().loadClientState().restoreEnabled, true)
+  assert.equal(harness(t, { version: 1 }).create().loadClientState().restoreEnabled, true)
+  assert.equal(harness(t, { version: 1, restoreEnabled: false }).create().loadClientState().restoreEnabled, false)
+})
+
+test("cross-host ownership is required in addition to each host-local election", async (t) => {
+  const root = mkdtempSync(join(tmpdir(), "codenomad-cross-host-state-"))
+  const electronDirectory = join(root, "electron"), tauriDirectory = join(root, "tauri"), election = join(root, "election")
+  t.after(() => rmSync(root, { recursive: true, force: true }))
+  const identities = new Map([[8101, "tauri-start"], [8102, "electron-start"], [8103, "successor-start"]])
+  const crossHostDependencies = { pidAlive: (pid: number) => identities.has(pid), processStartIdentity: (pid: number) => identities.get(pid) }
+  const primary = new ClientStateManager(tauriDirectory, undefined, {
+    crossHostElectionDirectory: election,
+    crossHostDependencies,
+    processOwner: { pid: 8101, runToken: "tauri", processStartIdentity: "tauri-start" },
+  })
+  mkdirSync(electronDirectory)
+  writeFileSync(join(electronDirectory, "client-state.json"), JSON.stringify({
+    version: 1,
+    restoreEnabled: true,
+    snapshot: { tabs: ["must-not-restore"] },
+  }))
+  const secondary = new ClientStateManager(electronDirectory, undefined, {
+    crossHostElectionDirectory: election,
+    crossHostDependencies,
+    processOwner: { pid: 8102, runToken: "electron", processStartIdentity: "electron-start" },
+  })
+  assert.deepEqual(secondary.loadClientState(), { isPrimary: false, restoreEnabled: false, snapshot: null })
+  await secondary.drainAndReleasePrimary()
+
+  await primary.drainAndReleasePrimary()
+  identities.delete(8101); identities.delete(8102)
+  const successor = new ClientStateManager(electronDirectory, undefined, {
+    crossHostElectionDirectory: election,
+    crossHostDependencies,
+    processOwner: { pid: 8103, runToken: "successor", processStartIdentity: "successor-start" },
+  })
+  assert.equal(successor.isPrimary, true)
+  await successor.drainAndReleasePrimary()
+})
+
+test("first shared primary deterministically migrates legacy host envelopes", async (t) => {
+  const root = mkdtempSync(join(tmpdir(), "codenomad-migration-"))
+  const electron = join(root, "electron"), tauri = join(root, "tauri"), election = join(root, "shared", "election")
+  mkdirSync(electron, { recursive: true }); mkdirSync(tauri, { recursive: true })
+  t.after(() => rmSync(root, { recursive: true, force: true }))
+  writeFileSync(join(electron, "client-state.json"), JSON.stringify({ version: 1, restoreEnabled: true, snapshot: { revision: 999, savedAt: 10, host: "electron" } }))
+  writeFileSync(join(tauri, "client-state.json"), JSON.stringify({
+    version: 1,
+    restoreEnabled: true,
+    snapshot: { savedAt: 20, host: "tauri" },
+    window: { bounds: { x: 10, y: 10, width: 1000, height: 700 }, maximized: false, fullscreen: false, zoomFactor: 1 },
+  }))
+  const manager = new ClientStateManager(electron, undefined, { crossHostElectionDirectory: election, legacyTauriDataPath: tauri })
+  assert.deepEqual(manager.loadClientState().snapshot, { savedAt: 20, host: "tauri" })
+  assert.equal(manager.getWindowState(), undefined)
+  assert.equal(existsSync(join(electron, "client-state.json")), false)
+  assert.equal(existsSync(join(tauri, "client-state.json")), false)
+  await manager.drainAndReleasePrimary()
+})
+
+test("legacy migration prefers disabled and ignores malformed candidates", async (t) => {
+  const root = mkdtempSync(join(tmpdir(), "codenomad-migration-"))
+  const electron = join(root, "electron"), tauri = join(root, "tauri"), election = join(root, "shared", "election")
+  mkdirSync(electron, { recursive: true }); mkdirSync(tauri, { recursive: true })
+  t.after(() => rmSync(root, { recursive: true, force: true }))
+  writeFileSync(join(electron, "client-state.json"), "malformed")
+  writeFileSync(join(tauri, "client-state.json"), JSON.stringify({ version: 1, restoreEnabled: false, snapshot: { savedAt: 1 } }))
+  const manager = new ClientStateManager(electron, undefined, { crossHostElectionDirectory: election, legacyTauriDataPath: tauri })
+  assert.deepEqual(manager.loadClientState(), { isPrimary: true, restoreEnabled: false, snapshot: null })
+  assert.equal(JSON.parse(readFileSync(join(root, "shared", "client-state.json"), "utf8")).restoreEnabled, false)
+  await manager.drainAndReleasePrimary()
+})
+
+test("legacy migration does not resurrect a snapshot after clear", async (t) => {
+  const root = mkdtempSync(join(tmpdir(), "codenomad-migration-"))
+  const electron = join(root, "electron"), tauri = join(root, "tauri"), election = join(root, "shared", "election")
+  mkdirSync(electron, { recursive: true }); mkdirSync(tauri, { recursive: true })
+  t.after(() => rmSync(root, { recursive: true, force: true }))
+  writeFileSync(join(electron, "client-state.json"), JSON.stringify({ version: 1, restoreEnabled: true }))
+  writeFileSync(join(tauri, "client-state.json"), JSON.stringify({ version: 1, restoreEnabled: true, snapshot: { savedAt: 20 } }))
+  const manager = new ClientStateManager(electron, undefined, { crossHostElectionDirectory: election, legacyTauriDataPath: tauri })
+  assert.equal(manager.loadClientState().snapshot, null)
+  await manager.drainAndReleasePrimary()
+})
+
+test("legacy cleanup failure cannot abort startup after shared state replacement", async (t) => {
+  const root = mkdtempSync(join(tmpdir(), "codenomad-migration-"))
+  const electron = join(root, "electron"), shared = join(root, "shared"), election = join(shared, "election")
+  mkdirSync(electron, { recursive: true })
+  t.after(() => rmSync(root, { recursive: true, force: true }))
+  writeFileSync(join(electron, "client-state.json"), JSON.stringify({ version: 1, restoreEnabled: true, snapshot: { savedAt: 10 } }))
+
+  const manager = new ClientStateManager(electron, undefined, {
+    crossHostElectionDirectory: election,
+    removeLegacyState: () => { throw new Error("injected cleanup failure") },
+  })
+  assert.deepEqual(manager.loadClientState().snapshot, { savedAt: 10 })
+  assert.equal(existsSync(join(shared, "client-state.json")), true)
+  await manager.drainAndReleasePrimary()
+})
+
+test("ownership loss immediately disables restore reads and mutations", async (t) => {
+  const h = harness(t, {
+    version: 1,
+    restoreEnabled: true,
+    snapshot: { tabs: ["must-stop"] },
+    window: { width: 900, height: 700 },
+  })
+  const manager = h.create()
+  writeFileSync(join(h.directory, "election", "primary.owner.json", "owner.json"), "malformed")
+  assert.equal(manager.isPrimary, false)
+  assert.deepEqual(manager.loadClientState(), { isPrimary: false, restoreEnabled: false, snapshot: null })
+  assert.equal(manager.getWindowState(), undefined)
+  assert.equal(await manager.saveClientState({ ignored: true }), false)
+})
+
+test("failed preference and clear writes roll memory and suppression back", async (t) => {
+  const h = harness(t, { version: 1, restoreEnabled: true })
+  const manager = h.create()
+  await manager.saveClientState({ kept: true })
+  h.fail(true)
+  await assert.rejects(manager.setRestoreEnabled(false), /injected write failure/)
+  assert.deepEqual(manager.loadClientState(), { isPrimary: true, restoreEnabled: true, snapshot: { kept: true } })
+  assert.equal(JSON.parse(readFileSync(h.statePath, "utf8")).restoreEnabled, true)
+  await assert.rejects(manager.clearClientState(), /injected write failure/)
+  h.fail(false)
+  await manager.setRestoreEnabled(true)
+  const before = h.writes()
+  await manager.saveClientState({ replacement: true })
+  assert.equal(h.writes(), before + 1)
+  assert.deepEqual(manager.loadClientState().snapshot, { replacement: true })
+})
+
+test("successful clear suppresses saves, including after failed re-enable", async (t) => {
+  const h = harness(t, { version: 1, restoreEnabled: true })
+  const manager = h.create()
+  await manager.saveClientState({ kept: true })
+  await manager.clearClientState()
+  h.fail(true)
+  await assert.rejects(manager.setRestoreEnabled(true), /injected write failure/)
+  const before = h.writes()
+  assert.equal(await manager.saveClientState({ ignored: true }), true)
+  assert.equal(h.writes(), before)
+  assert.equal(manager.loadClientState().snapshot, null)
+})
+
+test("disabling restore atomically removes snapshot/window and survives restart", async (t) => {
+  const h = harness(t, { version: 1, restoreEnabled: true })
+  const manager = h.create(undefined, { pid: process.pid, runToken: "before-restart", processStartIdentity: "old-start" })
+  await manager.saveClientState({ kept: true })
+  await manager.saveWindowState({ bounds: { x: 10, y: 20, width: 1200, height: 800 }, maximized: true, fullscreen: false, zoomFactor: 1.25 })
+  const before = h.writes()
+  assert.equal(await manager.setRestoreEnabled(false), true)
+  assert.equal(h.writes(), before + 1)
+  assert.deepEqual(manager.loadClientState(), { isPrimary: true, restoreEnabled: false, snapshot: null })
+  assert.equal(manager.getWindowState(), undefined)
+  const disabled = JSON.stringify({ version: 1, restoreEnabled: false })
+  assert.equal(readFileSync(h.statePath, "utf8"), disabled)
+  await manager.drainAndReleasePrimary()
+  const restarted = h.create()
+  assert.equal(await restarted.saveWindowState({ bounds: { x: 0, y: 0, width: 800, height: 600 }, maximized: false, fullscreen: false, zoomFactor: 1 }), true)
+  assert.equal(readFileSync(h.statePath, "utf8"), disabled)
+})
+
+test("drain freezes mutations and waits for admitted writes", async (t) => {
+  const h = harness(t, { version: 1, restoreEnabled: true })
+  let started!: () => void
+  let release!: () => void
+  const began = new Promise<void>((resolve) => { started = resolve })
+  const gate = new Promise<void>((resolve) => { release = resolve })
+  const manager = h.create(async (path, value) => { await writeFile(path, value); started(); await gate })
+  const admitted = manager.saveClientState({ admitted: true })
+  await began
+  let settled = false
+  const drain = manager.drainAndReleasePrimary().finally(() => { settled = true })
+  await assert.rejects(manager.saveClientState({ late: true }), /frozen for shutdown/)
+  await new Promise((resolve) => setImmediate(resolve))
+  assert.equal(settled, false)
+  assert.equal(manager.isPrimary, true)
+  release()
+  await Promise.all([admitted, drain])
+  assert.equal(manager.isPrimary, false)
+  assert.deepEqual(JSON.parse(readFileSync(h.statePath, "utf8")).snapshot, { admitted: true })
+})
+
+test("an old writer cannot replace a successor after PID reuse", async (t) => {
+  const h = harness(t, { version: 1, restoreEnabled: true })
+  let started!: () => void
+  let release!: () => void
+  const began = new Promise<void>((resolve) => { started = resolve })
+  const gate = new Promise<void>((resolve) => { release = resolve })
+  const old = h.create(
+    async (path, value) => { await writeFile(path, value); started(); await gate },
+    { pid: process.pid, runToken: "old-run", processStartIdentity: "old-start" },
+  )
+  const staleWrite = old.saveClientState({ stale: true })
+  await began
+  const oldDrain = old.drainAndReleasePrimary()
+  const successor = h.create()
+  assert.equal(successor.isPrimary, true)
+  await successor.saveClientState({ successor: true })
+  release()
+  await assert.rejects(staleWrite, /ownership changed before atomic replacement/)
+  await assert.rejects(oldDrain, /ownership changed before atomic replacement/)
+  assert.deepEqual(JSON.parse(readFileSync(h.statePath, "utf8")).snapshot, { successor: true })
+})
+
+test("future envelopes are preserved until a successful explicit clear", async (t) => {
+  const future = { version: 7, restoreEnabled: false, snapshot: { future: true }, futurePreference: "keep" }
+  const h = harness(t, future)
+  const manager = h.create(undefined, { pid: process.pid, runToken: "future-before-restart", processStartIdentity: "old-start" })
+  assert.deepEqual(manager.loadClientState(), { isPrimary: true, restoreEnabled: false, snapshot: null })
+  assert.equal(await manager.saveClientState({ ignored: true }), true)
+  assert.equal(await manager.setRestoreEnabled(false), false)
+  assert.deepEqual(JSON.parse(readFileSync(h.statePath, "utf8")), future)
+  await manager.drainAndReleasePrimary()
+  const restarted = h.create()
+  assert.deepEqual(JSON.parse(readFileSync(h.statePath, "utf8")), future)
+  assert.equal(await restarted.clearClientState(), true)
+  assert.deepEqual(JSON.parse(readFileSync(h.statePath, "utf8")), { version: 1, restoreEnabled: false })
+  assert.equal(await restarted.saveClientState({ supported: true }), true)
+  assert.deepEqual(JSON.parse(readFileSync(h.statePath, "utf8")).snapshot, { supported: true })
+})
+
+test("failed future-envelope clear leaves persistence blocked", async (t) => {
+  const future = { version: 7, future: true }
+  const h = harness(t, future)
+  let writes = 0
+  const manager = h.create(async () => { writes++; throw new Error("clear failed") })
+  await assert.rejects(manager.clearClientState(), /clear failed/)
+  assert.equal(await manager.setRestoreEnabled(false), false)
+  assert.equal(await manager.saveClientState({ ignored: true }), true)
+  assert.equal(writes, 1)
+  assert.deepEqual(JSON.parse(readFileSync(h.statePath, "utf8")), future)
+})
diff --git a/packages/electron-app/electron/main/client-state.ts b/packages/electron-app/electron/main/client-state.ts
new file mode 100644
index 00000000..98b09320
--- /dev/null
+++ b/packages/electron-app/electron/main/client-state.ts
@@ -0,0 +1,511 @@
+import { randomUUID } from "node:crypto"
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { open, rename, rm } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import {
+  electClientStateProcess,
+  getRunningMarkerPath,
+  hasLiveTauriClient,
+  hasErrorCode,
+  isProcessOwnerLockOwned,
+  removeProcessOwnerLockIfOwned,
+  type ProcessOwner,
+  removeRunningMarkerIfOwned,
+} from "./client-state-process"
+import { getProcessStartIdentity } from "./client-state-process-identity"
+import {
+  CrossHostRegistration,
+  crossHostParticipants,
+  resolveCrossHostElectionDirectory,
+  resolveCrossHostStatePath,
+  resolveLegacyTauriDataDirectory,
+  type CrossHostLeaseDependencies,
+} from "./client-state-cross-host"
+import { normalizeNativeWindowState } from "./window-state"
+
+const CLIENT_STATE_VERSION = 1
+const CLIENT_STATE_FILENAME = "client-state.json"
+const PRIMARY_LOCK_FILENAME = "client-state.primary.lock"
+const REGISTRATION_LOCK_FILENAME = "client-state.registration.lock"
+
+export const MAX_CLIENT_SNAPSHOT_BYTES = 1024 * 1024
+
+export interface WindowBounds {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface NativeWindowState {
+  bounds: WindowBounds
+  maximized: boolean
+  fullscreen: boolean
+  zoomFactor: number
+}
+
+export interface ClientStateLoadResult {
+  isPrimary: boolean
+  restoreEnabled: boolean
+  snapshot: unknown | null
+}
+
+interface PersistedClientState {
+  version: typeof CLIENT_STATE_VERSION
+  restoreEnabled: boolean
+  snapshot?: unknown
+  window?: NativeWindowState
+}
+
+export type ClientStateWriter = (
+  temporaryPath: string,
+  serializedState: string,
+) => Promise<void>
+
+interface ClientStateManagerOptions {
+  crossHostElectionDirectory?: string
+  crossHostDependencies?: CrossHostLeaseDependencies
+  legacyTauriDataPath?: string | null
+  processOwner?: ProcessOwner
+  removeLegacyState?(path: string): void
+}
+
+async function writeClientStateTemporary(temporaryPath: string, serializedState: string): Promise<void> {
+  const file = await open(temporaryPath, "w", 0o600)
+  try {
+    await file.writeFile(serializedState, "utf8")
+    await file.sync()
+  } finally {
+    await file.close()
+  }
+}
+
+interface ParsedClientState {
+  state: PersistedClientState
+  unsupportedFutureEnvelope: boolean
+}
+
+function parseClientState(value: string): ParsedClientState {
+  const defaults: PersistedClientState = { version: CLIENT_STATE_VERSION, restoreEnabled: true }
+  try {
+    const candidate = JSON.parse(value) as Record<string, unknown>
+    if (candidate && typeof candidate.version === "number" && candidate.version > CLIENT_STATE_VERSION) {
+      return { state: { ...defaults, restoreEnabled: false }, unsupportedFutureEnvelope: true }
+    }
+    if (!candidate || candidate.version !== CLIENT_STATE_VERSION) {
+      return { state: defaults, unsupportedFutureEnvelope: false }
+    }
+
+    const state: PersistedClientState = {
+      version: CLIENT_STATE_VERSION,
+      restoreEnabled: typeof candidate.restoreEnabled === "boolean" ? candidate.restoreEnabled : true,
+    }
+    if (Object.prototype.hasOwnProperty.call(candidate, "snapshot")) {
+      state.snapshot = candidate.snapshot
+    }
+    const windowState = normalizeNativeWindowState(candidate.window)
+    if (windowState) {
+      state.window = windowState
+    }
+    return { state, unsupportedFutureEnvelope: false }
+  } catch (error) {
+    console.warn("[client-state] ignored invalid state file", error)
+    return { state: defaults, unsupportedFutureEnvelope: false }
+  }
+}
+
+function legacyCandidate(path: string, host: "electron" | "tauri"): { host: string; state: PersistedClientState; savedAt: number; hasSnapshot: boolean } | undefined {
+  try {
+    const candidate = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>
+    if (!candidate || candidate.version !== CLIENT_STATE_VERSION) return undefined
+    const parsed = parseClientState(JSON.stringify(candidate)).state
+    delete parsed.window
+    const snapshot = candidate.snapshot as Record<string, unknown> | undefined
+    const savedAt = typeof snapshot?.savedAt === "number" && Number.isFinite(snapshot.savedAt) ? snapshot.savedAt : -1
+    return { host, state: parsed, savedAt, hasSnapshot: snapshot !== undefined }
+  } catch {
+    return undefined
+  }
+}
+
+function isFutureLegacyCandidate(path: string): boolean {
+  try {
+    const candidate = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>
+    return typeof candidate?.version === "number" && candidate.version > CLIENT_STATE_VERSION
+  } catch {
+    return false
+  }
+}
+
+export class ClientStateManager {
+  private readonly userDataPath: string
+  private readonly statePath: string
+  private readonly lockPath: string
+  private readonly legacyTauriDataPath: string | null
+  private readonly owner: ProcessOwner
+  private state: PersistedClientState = { version: CLIENT_STATE_VERSION, restoreEnabled: true }
+  private writeQueue: Promise<void> = Promise.resolve()
+  private drainAndReleasePromise: Promise<void> | undefined
+  private crossHostRegistration: CrossHostRegistration | undefined
+  private primary = false
+  private persistenceSuppressed = false
+  private unsupportedFutureEnvelope = false
+  private frozen = false
+  private rendererAccessToken: string | undefined
+
+  constructor(
+    userDataPath: string,
+    private readonly writeState: ClientStateWriter = writeClientStateTemporary,
+    options?: ClientStateManagerOptions,
+  ) {
+    this.owner = options?.processOwner ?? {
+      pid: process.pid,
+      runToken: randomUUID(),
+      processStartIdentity: getProcessStartIdentity(process.pid),
+    }
+    mkdirSync(userDataPath, { recursive: true })
+    this.userDataPath = userDataPath
+    const crossHostElectionDirectory = options?.crossHostElectionDirectory ?? resolveCrossHostElectionDirectory()
+    this.statePath = options?.crossHostElectionDirectory
+      ? join(dirname(crossHostElectionDirectory), CLIENT_STATE_FILENAME)
+      : resolveCrossHostStatePath()
+    mkdirSync(dirname(this.statePath), { recursive: true })
+    this.lockPath = join(userDataPath, PRIMARY_LOCK_FILENAME)
+    const registrationLockPath = join(userDataPath, REGISTRATION_LOCK_FILENAME)
+
+    const election = electClientStateProcess(
+      userDataPath,
+      this.owner,
+      { primaryLockPath: this.lockPath, registrationLockPath },
+      (message, error) => console.warn(`[client-state] ${message}`, error),
+    )
+    const legacyTauriDataPath = options?.legacyTauriDataPath === undefined
+      ? (options?.crossHostElectionDirectory ? null : resolveLegacyTauriDataDirectory())
+      : options.legacyTauriDataPath
+    this.legacyTauriDataPath = legacyTauriDataPath
+    this.primary = election
+    try {
+      this.crossHostRegistration = CrossHostRegistration.register(
+        crossHostElectionDirectory,
+        this.owner,
+        () => {
+          if (!this.primary || !legacyTauriDataPath) return this.primary
+          try {
+            return !hasLiveTauriClient(
+              legacyTauriDataPath,
+              options?.crossHostDependencies?.pidAlive,
+              options?.crossHostDependencies?.processStartIdentity,
+              undefined,
+              crossHostParticipants(crossHostElectionDirectory),
+            )
+          } catch (error) {
+            console.warn("[client-state] failed to inspect legacy Tauri process markers; continuing as secondary", error)
+            return false
+          }
+        },
+        options?.crossHostDependencies,
+      )
+    } catch (error) {
+      console.warn("[client-state] failed to register cross-host ownership", error)
+    }
+    if (!this.crossHostRegistration?.isPrimary) {
+      if (election) removeProcessOwnerLockIfOwned(this.lockPath, this.owner)
+      this.primary = false
+    }
+    if (this.isPrimary) {
+      const legacyPaths = [
+        ["electron", join(userDataPath, CLIENT_STATE_FILENAME)],
+        ...(legacyTauriDataPath ? [["tauri", join(legacyTauriDataPath, CLIENT_STATE_FILENAME)] as const] : []),
+      ] as ReadonlyArray<readonly ["electron" | "tauri", string]>
+      this.migrateLegacyStateIfNeeded(legacyPaths, options?.removeLegacyState)
+      const futureLegacyBlocked = this.unsupportedFutureEnvelope
+      const persisted = this.readState()
+      this.state = futureLegacyBlocked
+        ? { version: CLIENT_STATE_VERSION, restoreEnabled: false }
+        : persisted.state
+      this.persistenceSuppressed = !this.state.restoreEnabled
+      this.unsupportedFutureEnvelope = futureLegacyBlocked || persisted.unsupportedFutureEnvelope
+    }
+  }
+
+  get isPrimary(): boolean {
+    if (!this.primary || !this.crossHostRegistration?.isPrimary) return false
+    if (!this.legacyTauriDataPath) return true
+    try {
+      return !hasLiveTauriClient(this.legacyTauriDataPath, undefined, undefined, undefined, crossHostParticipants(this.crossHostRegistration.path))
+    } catch (error) {
+      console.warn("[client-state] failed to recheck legacy Tauri process markers; ownership disabled", error)
+      return false
+    }
+  }
+
+  loadClientState(): ClientStateLoadResult {
+    if (!this.isPrimary) {
+      return { isPrimary: false, restoreEnabled: false, snapshot: null }
+    }
+    return {
+      isPrimary: true,
+      restoreEnabled: this.state.restoreEnabled,
+      snapshot: this.state.restoreEnabled ? (this.state.snapshot ?? null) : null,
+    }
+  }
+
+  getWindowState(): NativeWindowState | undefined {
+    return this.isPrimary && !this.unsupportedFutureEnvelope && this.state.restoreEnabled ? this.state.window : undefined
+  }
+
+  claimClientStateAccess(token: unknown): true {
+    this.validateRendererAccessTokenValue(token)
+    if (this.rendererAccessToken === undefined) {
+      this.rendererAccessToken = token
+      return true
+    }
+    if (this.rendererAccessToken !== token) {
+      throw new Error("Client state access token does not match the claimed renderer")
+    }
+    return true
+  }
+
+  assertRendererAccessToken(token: unknown): void {
+    this.validateRendererAccessTokenValue(token)
+    if (this.rendererAccessToken === undefined || this.rendererAccessToken !== token) {
+      throw new Error("Client state access has not been claimed by this renderer")
+    }
+  }
+
+  resetRendererAccessToken(): void {
+    this.rendererAccessToken = undefined
+  }
+
+  saveClientState(snapshot: unknown, rendererToken?: unknown): Promise<boolean> {
+    const disposition = this.getMutationDisposition()
+    if (disposition) return disposition
+
+    const serialized = JSON.stringify(snapshot)
+    if (serialized === undefined) {
+      throw new TypeError("Client snapshot must be JSON-serializable")
+    }
+    if (Buffer.byteLength(serialized, "utf8") > MAX_CLIENT_SNAPSHOT_BYTES) {
+      throw new RangeError("Client snapshot exceeds the 1 MiB limit")
+    }
+
+    const normalizedSnapshot = JSON.parse(serialized) as unknown
+    return this.mutateAndPersist((state) => {
+      state.snapshot = normalizedSnapshot
+    }, true, rendererToken)
+  }
+
+  setRestoreEnabled(enabled: boolean, rendererToken?: unknown): Promise<boolean> {
+    const disposition = this.getMutationDisposition(false)
+    if (disposition) return disposition
+
+    if (typeof enabled !== "boolean") {
+      throw new TypeError("Restore enabled must be a boolean")
+    }
+
+    return this.mutateAndPersist((state) => {
+      state.restoreEnabled = enabled
+      if (enabled) {
+        this.persistenceSuppressed = false
+      } else {
+        delete state.snapshot
+        delete state.window
+        this.persistenceSuppressed = true
+      }
+    }, false, rendererToken)
+  }
+
+  clearClientState(rendererToken?: unknown): Promise<boolean> {
+    if (!this.isPrimary) {
+      return Promise.resolve(false)
+    }
+    if (this.frozen) {
+      return Promise.reject(new Error("Client state persistence is frozen for shutdown"))
+    }
+
+    const clearingFutureEnvelope = this.unsupportedFutureEnvelope
+
+    return this.mutateAndPersist((state) => {
+      delete state.snapshot
+      delete state.window
+      this.unsupportedFutureEnvelope = false
+      this.persistenceSuppressed = !clearingFutureEnvelope
+    }, false, rendererToken)
+  }
+
+  saveWindowState(windowState: NativeWindowState): Promise<boolean> {
+    const disposition = this.getMutationDisposition()
+    if (disposition) return disposition
+
+    const normalized = normalizeNativeWindowState(windowState)
+    if (!normalized) {
+      return Promise.resolve(false)
+    }
+    return this.mutateAndPersist((state) => {
+      state.window = normalized
+    }, true)
+  }
+
+  async flush(): Promise<void> {
+    await this.writeQueue
+  }
+
+  drainAndReleasePrimary(): Promise<void> {
+    if (this.drainAndReleasePromise) {
+      return this.drainAndReleasePromise
+    }
+
+    this.frozen = true
+    this.drainAndReleasePromise = this.writeQueue.finally(() => {
+      this.primary = false
+      this.releaseOwnedProcessFiles()
+    })
+    return this.drainAndReleasePromise
+  }
+
+  private readState(): ParsedClientState {
+    try {
+      return parseClientState(readFileSync(this.statePath, "utf8"))
+    } catch (error) {
+      if (!hasErrorCode(error, "ENOENT")) {
+        console.warn("[client-state] failed to read state", error)
+      }
+      return {
+        state: { version: CLIENT_STATE_VERSION, restoreEnabled: true },
+        unsupportedFutureEnvelope: false,
+      }
+    }
+  }
+
+  private migrateLegacyStateIfNeeded(
+    paths: ReadonlyArray<readonly ["electron" | "tauri", string]>,
+    removeLegacyState = (path: string) => rmSync(path, { force: true }),
+  ): void {
+    try {
+      readFileSync(this.statePath)
+      return
+    } catch (error) {
+      if (!hasErrorCode(error, "ENOENT")) return
+    }
+    if (paths.some(([, path]) => isFutureLegacyCandidate(path))) {
+      this.unsupportedFutureEnvelope = true
+      return
+    }
+    const winner = paths
+      .map(([host, path]) => legacyCandidate(path, host))
+      .filter((candidate): candidate is NonNullable<typeof candidate> => Boolean(candidate))
+      .sort((left, right) =>
+        Number(left.state.restoreEnabled) - Number(right.state.restoreEnabled) ||
+        Number(left.hasSnapshot) - Number(right.hasSnapshot) ||
+        right.savedAt - left.savedAt ||
+        right.host.localeCompare(left.host),
+      )[0]
+    if (!winner) return
+
+    const temporaryPath = join(dirname(this.statePath), `.${CLIENT_STATE_FILENAME}.${this.owner.pid}.${this.owner.runToken}.migration.tmp`)
+    let descriptor: number | undefined
+    try {
+      descriptor = openSync(temporaryPath, "wx", 0o600)
+      writeFileSync(descriptor, JSON.stringify(winner.state), "utf8")
+      fsyncSync(descriptor)
+      closeSync(descriptor)
+      descriptor = undefined
+      this.assertReplacementAllowed()
+      renameSync(temporaryPath, this.statePath)
+      for (const [, path] of paths) {
+        try {
+          removeLegacyState(path)
+        } catch (error) {
+          console.warn(`[client-state] failed to remove migrated legacy state at ${path}`, error)
+        }
+      }
+    } finally {
+      if (descriptor !== undefined) closeSync(descriptor)
+      rm(temporaryPath, { force: true }).catch(() => {})
+    }
+  }
+
+  private getMutationDisposition(futureEnvelopeResult = true): Promise<boolean> | undefined {
+    if (!this.isPrimary) {
+      return Promise.resolve(false)
+    }
+    if (this.frozen) {
+      return Promise.reject(new Error("Client state persistence is frozen for shutdown"))
+    }
+    if (this.unsupportedFutureEnvelope) {
+      return Promise.resolve(futureEnvelopeResult)
+    }
+    return undefined
+  }
+
+  private mutateAndPersist(
+    mutate: (state: PersistedClientState) => void,
+    skipWhenSuppressed = false,
+    rendererToken?: unknown,
+  ): Promise<boolean> {
+    const operation = this.writeQueue.catch(() => {}).then(async () => {
+      if (rendererToken !== undefined) this.assertRendererAccessToken(rendererToken)
+      if (skipWhenSuppressed && this.persistenceSuppressed) {
+        return
+      }
+
+      const previousState = { ...this.state }
+      const previousPersistenceSuppressed = this.persistenceSuppressed
+      const previousUnsupportedFutureEnvelope = this.unsupportedFutureEnvelope
+      try {
+        mutate(this.state)
+        await this.writeAtomically(JSON.stringify(this.state), rendererToken)
+      } catch (error) {
+        this.state = previousState
+        this.persistenceSuppressed = previousPersistenceSuppressed
+        this.unsupportedFutureEnvelope = previousUnsupportedFutureEnvelope
+        throw error
+      }
+    })
+    this.writeQueue = operation
+    return operation.then(() => true)
+  }
+
+  private async writeAtomically(serializedState: string, rendererToken?: unknown): Promise<void> {
+    const temporaryPath = join(
+      dirname(this.statePath),
+      `.${CLIENT_STATE_FILENAME}.${this.owner.pid}.${this.owner.runToken}.tmp`,
+    )
+    try {
+      await this.writeState(temporaryPath, serializedState)
+      this.assertReplacementAllowed(rendererToken)
+      await rename(temporaryPath, this.statePath)
+    } catch (error) {
+      await rm(temporaryPath, { force: true }).catch(() => {})
+      throw error
+    }
+  }
+
+  private assertReplacementAllowed(rendererToken?: unknown): void {
+    if (rendererToken !== undefined) this.assertRendererAccessToken(rendererToken)
+    if (!this.isPrimary || !isProcessOwnerLockOwned(this.lockPath, this.owner)) {
+      throw new Error("Client state ownership changed before atomic replacement")
+    }
+  }
+
+  private releaseOwnedProcessFiles(): void {
+    const releases: Array<[string, () => void]> = [
+      ["remove running marker", () => { removeRunningMarkerIfOwned(getRunningMarkerPath(this.userDataPath, this.owner), this.owner) }],
+      ["release primary lock", () => { removeProcessOwnerLockIfOwned(this.lockPath, this.owner) }],
+      ["release cross-host registration", () => { this.crossHostRegistration?.release(); this.crossHostRegistration = undefined }],
+    ]
+    for (const [action, release] of releases) {
+      try {
+        release()
+      } catch (error) {
+        console.warn(`[client-state] failed to ${action}`, error)
+      }
+    }
+  }
+
+  private validateRendererAccessTokenValue(token: unknown): asserts token is string {
+    if (typeof token !== "string" || token.trim().length === 0) {
+      throw new TypeError("Client state access token must be a nonempty string")
+    }
+  }
+}
diff --git a/packages/electron-app/electron/main/ipc.ts b/packages/electron-app/electron/main/ipc.ts
index 076ec8ca..6e664d90 100644
--- a/packages/electron-app/electron/main/ipc.ts
+++ b/packages/electron-app/electron/main/ipc.ts
@@ -41,8 +41,7 @@ export function setupCliIPC(mainWindow: BrowserWindow, cliManager: CliProcessMan
 
   ipcMain.handle("cli:restart", async () => {
     const devMode = process.env.NODE_ENV === "development"
-    await cliManager.stop()
-    return cliManager.start({ dev: devMode })
+    return cliManager.restart({ dev: devMode })
   })
 
   ipcMain.handle("dialog:open", async (_, request: DialogOpenRequest): Promise<DialogOpenResult> => {
diff --git a/packages/electron-app/electron/main/main.ts b/packages/electron-app/electron/main/main.ts
index c4e01e29..f90fb361 100644
--- a/packages/electron-app/electron/main/main.ts
+++ b/packages/electron-app/electron/main/main.ts
@@ -1,13 +1,26 @@
-import { app, BrowserView, BrowserWindow, nativeImage, session, shell } from "electron"
+import { app, BrowserView, BrowserWindow, ipcMain, nativeImage, screen, session, shell } from "electron"
 import http from "node:http"
 import https from "node:https"
 import { existsSync, mkdirSync, rmSync } from "fs"
 import { dirname, join } from "path"
 import { fileURLToPath } from "url"
 import { createApplicationMenu } from "./menu"
+import { ClientStateManager } from "./client-state"
+import { setupClientStateIPC } from "./client-state-ipc"
+import { ClientStateLifecycle } from "./client-state-lifecycle"
+import { ClientStateNavigationController } from "./client-state-navigation"
 import { setupCliIPC } from "./ipc"
-import { configureMediaPermissionHandlers } from "./permissions"
+import { configureMediaPermissionHandlers, isAllowedRendererOrigin } from "./permissions"
+import { resolveConfiguredRendererOrigins } from "./renderer-origin"
 import { CliProcessManager } from "./process-manager"
+import {
+  clampWindowBounds,
+  DEFAULT_WINDOW_HEIGHT,
+  DEFAULT_WINDOW_WIDTH,
+  installWindowZoomInput,
+  restoreWindowState,
+  WindowStateTracker,
+} from "./window-state"
 
 const mainFilename = fileURLToPath(import.meta.url)
 const mainDirname = dirname(mainFilename)
@@ -82,6 +95,7 @@ function cleanupPackagedChromiumStorage() {
 
 cleanupPackagedChromiumStorage()
 
+const clientStateManager = new ClientStateManager(app.getPath("userData"))
 const cliManager = new CliProcessManager()
 let mainWindow: BrowserWindow | null = null
 let currentCliUrl: string | null = null
@@ -89,8 +103,24 @@ let pendingCliUrl: string | null = null
 let pendingBootstrapToken: string | null = null
 let showingLoadingScreen = false
 let preloadingView: BrowserView | null = null
+let mainNavigationController: ClientStateNavigationController | null = null
 const remoteWindowOrigins = new Map<number, Set<string>>()
 const insecureWindowOrigins = new Map<number, Set<string>>()
+const clientStateLifecycle = new ClientStateLifecycle({
+  app,
+  clientStateManager,
+  cliManager,
+  getMainWindow: () => mainWindow,
+  getAllWindows: () => BrowserWindow.getAllWindows(),
+  getAllowedRendererOrigins,
+  isTrustedRendererOrigin: isAllowedRendererOrigin,
+})
+const bindClientStateWindow = setupClientStateIPC(
+  ipcMain,
+  clientStateManager,
+  () => mainWindow,
+  getAllowedRendererOrigins,
+)
 
 if (isMac) {
   app.commandLine.appendSwitch("disable-spell-checking")
@@ -151,19 +181,18 @@ function resolveLoadingFilePath() {
   return join(app.getAppPath(), "dist/renderer/loading.html")
 }
 
-function loadLoadingScreen(window: BrowserWindow) {
+async function loadLoadingScreen(window: BrowserWindow): Promise<boolean> {
   const target = resolveLoadingTarget()
-  const loader =
-    target.type === "url"
-      ? window.loadURL(target.source)
-      : window.loadFile(target.source)
-
-  loader.catch((error) => {
+  try {
+    await (target.type === "url" ? window.loadURL(target.source) : window.loadFile(target.source))
+    return true
+  } catch (error) {
     if (isIgnorableNavigationError(error)) {
-      return
+      return false
     }
     console.error("[cli] failed to load loading screen:", error)
-  })
+    return false
+  }
 }
 
 function isIgnorableNavigationError(error: unknown): boolean {
@@ -183,16 +212,11 @@ function getAllowedRendererOrigins(window?: BrowserWindow | null): string[] {
       origins.add(origin)
     }
   }
-  const rendererCandidates = [currentCliUrl, process.env.VITE_DEV_SERVER_URL, process.env.ELECTRON_RENDERER_URL]
-  for (const candidate of rendererCandidates) {
-    if (!candidate) {
-      continue
-    }
-    try {
-      origins.add(new URL(candidate).origin)
-    } catch (error) {
-      console.warn("[cli] failed to parse origin for", candidate, error)
-    }
+  for (const origin of resolveConfiguredRendererOrigins(currentCliUrl, app.isPackaged, [
+    process.env.VITE_DEV_SERVER_URL,
+    process.env.ELECTRON_RENDERER_URL,
+  ])) {
+    origins.add(origin)
   }
   return Array.from(origins)
 }
@@ -210,7 +234,7 @@ function shouldOpenExternally(url: string, window?: BrowserWindow | null): boole
   }
 }
 
-function setupNavigationGuards(window: BrowserWindow) {
+function setupNavigationGuards(window: BrowserWindow, navigationController?: ClientStateNavigationController) {
   const handleExternal = (url: string) => {
     shell.openExternal(url).catch((error) => console.error("[cli] failed to open external URL", url, error))
   }
@@ -224,6 +248,20 @@ function setupNavigationGuards(window: BrowserWindow) {
   })
 
   window.webContents.on("will-navigate", (event, url) => {
+    if (shouldOpenExternally(url, window)) {
+      event.preventDefault()
+      handleExternal(url)
+    } else if (navigationController) {
+      event.preventDefault()
+      void navigationController.navigate((target) => target.loadURL(url)).catch((error) => {
+        if (!isIgnorableNavigationError(error)) {
+          console.error("[client-state] trusted renderer navigation failed", error)
+        }
+      })
+    }
+  })
+
+  window.webContents.on("will-redirect", (event, url) => {
     if (shouldOpenExternally(url, window)) {
       event.preventDefault()
       handleExternal(url)
@@ -240,6 +278,21 @@ function setWindowAllowedOrigin(window: BrowserWindow, url: string) {
   }
 }
 
+function stageWindowAllowedOrigin(window: BrowserWindow, url: string): () => void {
+  const previous = remoteWindowOrigins.get(window.id)
+  try {
+    const origins = new Set(previous)
+    origins.add(new URL(url).origin)
+    remoteWindowOrigins.set(window.id, origins)
+  } catch (error) {
+    console.warn("[cli] failed to stage allowed origin", url, error)
+  }
+  return () => {
+    if (previous) remoteWindowOrigins.set(window.id, previous)
+    else remoteWindowOrigins.delete(window.id)
+  }
+}
+
 function clearWindowAllowedOrigin(window: BrowserWindow) {
   remoteWindowOrigins.delete(window.id)
 }
@@ -320,10 +373,19 @@ function createWindow() {
   const prefersDark = true
   const backgroundColor = prefersDark ? "#1a1a1a" : "#ffffff"
   const iconPath = getIconPath()
+  const savedWindowState = clientStateManager.getWindowState()
+  const restoredBounds = savedWindowState
+    ? clampWindowBounds(
+        savedWindowState.bounds,
+        screen.getAllDisplays().map((display) => display.workArea),
+      )
+    : undefined
 
   mainWindow = new BrowserWindow({
-    width: 1400,
-    height: 900,
+    width: restoredBounds?.width ?? DEFAULT_WINDOW_WIDTH,
+    height: restoredBounds?.height ?? DEFAULT_WINDOW_HEIGHT,
+    useContentSize: true,
+    ...(restoredBounds ? { x: restoredBounds.x, y: restoredBounds.y } : {}),
     minWidth: 800,
     minHeight: 600,
     backgroundColor,
@@ -332,14 +394,36 @@ function createWindow() {
       preload: getPreloadPath(),
       contextIsolation: true,
       nodeIntegration: false,
+      ...(savedWindowState ? { zoomFactor: savedWindowState.zoomFactor } : {}),
       spellcheck: !isMac,
       additionalArguments: ["--codenomad-window-context=local"],
     },
   })
 
   const window = mainWindow
+  const navigationController = new ClientStateNavigationController(
+    window,
+    {
+      clientStateManager,
+      isTrustedOrigin: (url) => isAllowedRendererOrigin(url, getAllowedRendererOrigins(window)),
+      reportFlushError: (error) => {
+        console.warn("[client-state] renderer pre-navigation flush failed; continuing navigation", error)
+      },
+    },
+  )
+  mainNavigationController = navigationController
 
-  setupNavigationGuards(window)
+  let windowStateTracker: WindowStateTracker | null = null
+  if (clientStateManager.isPrimary) {
+    restoreWindowState(window, savedWindowState, restoredBounds)
+    windowStateTracker = new WindowStateTracker(window, clientStateManager, savedWindowState)
+  }
+  installWindowZoomInput(window, (level) => {
+    if (windowStateTracker) windowStateTracker.setZoomLevel(level)
+    else window.webContents.setZoomLevel(level)
+  })
+
+  setupNavigationGuards(window, navigationController)
 
   if (isMac) {
     window.webContents.session.setSpellCheckerEnabled(false)
@@ -348,23 +432,34 @@ function createWindow() {
   showingLoadingScreen = true
   currentCliUrl = null
   clearWindowAllowedOrigin(window)
-  loadLoadingScreen(window)
+  void loadLoadingScreen(window)
 
   if (process.env.NODE_ENV === "development") {
     window.webContents.openDevTools({ mode: "detach" })
   }
 
-  createApplicationMenu(window)
+  createApplicationMenu(window, {
+    reload: () => {
+      void navigationController.navigate((target) => target.webContents.reload())
+    },
+    forceReload: () => {
+      void navigationController.navigate((target) => target.webContents.reloadIgnoringCache())
+    },
+  })
   setupCliIPC(window, cliManager)
+  bindClientStateWindow(window)
+  clientStateLifecycle.attachMainWindow(window, windowStateTracker)
 
   window.on("closed", () => {
     destroyPreloadingView()
     clearWindowAllowedOrigin(window)
     clearWindowInsecureOrigin(window)
     mainWindow = null
+    if (mainNavigationController === navigationController) mainNavigationController = null
     currentCliUrl = null
     pendingCliUrl = null
     showingLoadingScreen = false
+    clientStateLifecycle.detachMainWindow(window)
   })
 
   if (pendingCliUrl) {
@@ -383,11 +478,19 @@ function showLoadingScreen(force = false) {
     return
   }
 
-  destroyPreloadingView()
+  const window = mainWindow
+  const wasShowingLoadingScreen = showingLoadingScreen
   showingLoadingScreen = true
-  currentCliUrl = null
+  destroyPreloadingView()
   pendingCliUrl = null
-  loadLoadingScreen(mainWindow)
+  void mainNavigationController?.navigate(async (target) => {
+    if (!(await loadLoadingScreen(target))) {
+      showingLoadingScreen = wasShowingLoadingScreen
+      return
+    }
+    currentCliUrl = null
+    clearWindowAllowedOrigin(target)
+  })
 }
 
 function isBootstrapTokenUrl(url: string): boolean {
@@ -460,16 +563,23 @@ function finalizeCliSwap(url: string) {
     return
   }
 
-  const window = mainWindow
-  showingLoadingScreen = false
-  currentCliUrl = url
-  setWindowAllowedOrigin(window, url)
-  pendingCliUrl = null
-  window.loadURL(url).catch((error) => {
-    if (isIgnorableNavigationError(error)) {
-      return
+  const navigate = async (target: BrowserWindow) => {
+    const rollbackOrigin = stageWindowAllowedOrigin(target, url)
+    try {
+      await target.loadURL(url)
+    } catch (error) {
+      rollbackOrigin()
+      throw error
     }
-    console.error("[cli] failed to load CLI view:", error)
+    showingLoadingScreen = false
+    currentCliUrl = url
+    setWindowAllowedOrigin(target, url)
+    pendingCliUrl = null
+  }
+  void mainNavigationController?.navigate(navigate).then(() => {
+    if (cliManager.getStatus().state !== "ready") showLoadingScreen()
+  }).catch((error) => {
+    if (!isIgnorableNavigationError(error)) console.error("[cli] failed to load CLI view:", error)
   })
 }
 
@@ -727,13 +837,4 @@ app.whenReady().then(() => {
   })
 })
 
-app.on("before-quit", async (event) => {
-  event.preventDefault()
-  await cliManager.stop().catch(() => {})
-  app.exit(0)
-})
-
-app.on("window-all-closed", () => {
-  // CodeNomad supports a single window; closing it should quit the app on all platforms.
-  app.quit()
-})
+clientStateLifecycle.registerAppEvents()
diff --git a/packages/electron-app/electron/main/menu.ts b/packages/electron-app/electron/main/menu.ts
index 37f9e340..7ecbc195 100644
--- a/packages/electron-app/electron/main/menu.ts
+++ b/packages/electron-app/electron/main/menu.ts
@@ -1,6 +1,11 @@
 import { Menu, BrowserWindow, MenuItemConstructorOptions } from "electron"
 
-export function createApplicationMenu(mainWindow: BrowserWindow) {
+interface ApplicationMenuActions {
+  reload(): void
+  forceReload(): void
+}
+
+export function createApplicationMenu(mainWindow: BrowserWindow, actions: ApplicationMenuActions) {
   const isMac = process.platform === "darwin"
 
   const template: MenuItemConstructorOptions[] = [
@@ -51,8 +56,8 @@ export function createApplicationMenu(mainWindow: BrowserWindow) {
     {
       label: "View",
       submenu: [
-        { role: "reload" as const },
-        { role: "forceReload" as const },
+        { label: "Reload", accelerator: "CmdOrCtrl+R", click: actions.reload },
+        { label: "Force Reload", accelerator: "CmdOrCtrl+Shift+R", click: actions.forceReload },
         { role: "toggleDevTools" as const },
         { type: "separator" as const },
         { role: "resetZoom" as const },
diff --git a/packages/electron-app/electron/main/permissions.ts b/packages/electron-app/electron/main/permissions.ts
index 28652321..5e1bf4f8 100644
--- a/packages/electron-app/electron/main/permissions.ts
+++ b/packages/electron-app/electron/main/permissions.ts
@@ -1,20 +1,10 @@
 import { session, systemPreferences } from "electron"
+import { isAllowedRendererOrigin } from "./renderer-origin"
+
+export { isAllowedRendererOrigin } from "./renderer-origin"
 
 const isMac = process.platform === "darwin"
 
-export function isAllowedRendererOrigin(origin: string | undefined | null, allowedOrigins: string[]): boolean {
-  if (!origin) {
-    return false
-  }
-
-  try {
-    const normalized = new URL(origin).origin
-    return allowedOrigins.includes(normalized)
-  } catch {
-    return false
-  }
-}
-
 export function configureMediaPermissionHandlers(getAllowedOrigins: () => string[]) {
   const isAudioMediaRequest = (permission: string, details?: unknown) => {
     if (permission !== "media") {
diff --git a/packages/electron-app/electron/main/process-manager.ts b/packages/electron-app/electron/main/process-manager.ts
index a1cd35e0..090de0d1 100644
--- a/packages/electron-app/electron/main/process-manager.ts
+++ b/packages/electron-app/electron/main/process-manager.ts
@@ -1,5 +1,5 @@
-import { spawn, spawnSync, type ChildProcess } from "child_process"
-import { app, utilityProcess, type UtilityProcess } from "electron"
+import { spawn, type ChildProcess } from "child_process"
+import { app } from "electron"
 import { createRequire } from "module"
 import { EventEmitter } from "events"
 import { existsSync, readFileSync } from "fs"
@@ -8,6 +8,16 @@ import path from "path"
 import { fileURLToPath } from "url"
 import { parse as parseYaml } from "yaml"
 import { ensureManagedNodeBinary } from "./managed-node"
+import { getProcessStartIdentityAsync } from "./client-state-process-identity"
+import {
+  CLI_STOP_DEADLINE_MS,
+  captureInitialProcessTree,
+  captureProcessTree,
+  forceCapturedProcessTree,
+  mergeCapturedProcessTrees,
+  stopManagedChild,
+} from "./process-stop"
+import { SerializedLifecycle } from "./serialized-lifecycle"
 import { buildUserShellCommand, getUserShellEnv, supportsUserShell } from "./user-shell"
 
 const nodeRequire = createRequire(import.meta.url)
@@ -15,8 +25,9 @@ const mainFilename = fileURLToPath(import.meta.url)
 const mainDirname = path.dirname(mainFilename)
 
 const BOOTSTRAP_TOKEN_PREFIX = "CODENOMAD_BOOTSTRAP_TOKEN:"
+const SERVER_SHUTDOWN_COMPLETE = "CODENOMAD_SHUTDOWN_STATUS:complete"
+const SERVER_SHUTDOWN_INCOMPLETE = "CODENOMAD_SHUTDOWN_STATUS:incomplete"
 const SESSION_COOKIE_NAME_PREFIX = "codenomad_session"
-
 type CliState = "starting" | "ready" | "error" | "stopped"
 type ListeningMode = "local" | "all"
 
@@ -45,9 +56,6 @@ interface CliEntryResolution {
   nodeArgs?: string[]
 }
 
-type ManagedChild = ChildProcess | UtilityProcess
-type ChildLaunchMode = "spawn" | "utility"
-
 const DEFAULT_CONFIG_PATH = "~/.config/codenomad/config.json"
 
 function isYamlPath(filePath: string): boolean {
@@ -127,18 +135,42 @@ export declare interface CliProcessManager {
 }
 
 export class CliProcessManager extends EventEmitter {
-  private child?: ManagedChild
-  private childLaunchMode: ChildLaunchMode = "spawn"
+  private child?: ChildProcess
+  private childStartIdentity?: Promise<string | undefined>
   private status: CliStatus = { state: "stopped" }
   private stdoutBuffer = ""
   private stderrBuffer = ""
   private bootstrapToken: string | null = null
   private authCookieName = `${SESSION_COOKIE_NAME_PREFIX}_${process.pid}_${Date.now()}`
   private requestedStop = false
+  private shutdownStatus: "complete" | "incomplete" | null = null
+  private lifecycle = new SerializedLifecycle()
 
-  async start(options: StartOptions): Promise<CliStatus> {
+  start(options: StartOptions): Promise<CliStatus> {
+    return this.lifecycle.enqueue(() => this.startNow(options))
+  }
+
+  restart(options: StartOptions): Promise<CliStatus> {
+    return this.lifecycle.enqueue(async () => {
+      await this.stopNow()
+      if (this.lifecycle.stopped) throw new Error("CLI process manager is shutting down")
+      return this.startNow(options)
+    })
+  }
+
+  stop(): Promise<void> {
+    return this.lifecycle.enqueue(() => this.stopNow())
+  }
+
+  shutdown(): Promise<void> {
+    return this.lifecycle.stop(() => this.stopNow())
+  }
+
+  private async startNow(options: StartOptions): Promise<CliStatus> {
+    if (this.lifecycle.stopped) throw new Error("CLI process manager is shutting down")
     if (this.child) {
-      await this.stop()
+      await this.stopNow()
+      if (this.child) throw new Error("CLI process did not exit before restart")
     }
 
     this.stdoutBuffer = ""
@@ -146,6 +178,8 @@ export class CliProcessManager extends EventEmitter {
     this.bootstrapToken = null
     this.authCookieName = `${SESSION_COOKIE_NAME_PREFIX}_${process.pid}_${Date.now()}`
     this.requestedStop = false
+    this.shutdownStatus = null
+    this.childStartIdentity = undefined
     this.updateStatus({ state: "starting", port: undefined, pid: undefined, url: undefined, error: undefined })
 
     const listeningMode = this.resolveListeningMode()
@@ -153,63 +187,32 @@ export class CliProcessManager extends EventEmitter {
     const args = this.buildCliArgs(options, host)
     const cliEntry = await this.resolveCliEntry(options)
 
-    let child: ManagedChild
+    console.info(
+      `[cli] launching CodeNomad CLI (${options.dev ? "dev" : "prod"}) using ${cliEntry.runner} at ${cliEntry.entry} (host=${host})`,
+    )
 
-    if (this.shouldUsePackagedShellSupervisor(options)) {
-      const runtimePath = this.resolveShellNodeCommand()
-      const entryPath = this.resolveBundledProdEntry()
-      const supervisorPath = this.resolveCliSupervisorPath()
-      const shellEnv = supportsUserShell() ? getUserShellEnv() : { ...process.env }
-      const shellTarget = this.buildCommand(cliEntry, args)
-      const shellCommand = buildUserShellCommand(`exec ${shellTarget}`)
-      const supervisorPayload = JSON.stringify({
-        command: shellCommand.command,
-        args: shellCommand.args,
-        cwd: process.cwd(),
-      })
+    const env = supportsUserShell() ? getUserShellEnv() : { ...process.env }
+    env.ELECTRON_RUN_AS_NODE = "1"
 
-      console.info(
-        `[cli] launching CodeNomad CLI (${options.dev ? "dev" : "prod"}) via utility supervisor using node at ${runtimePath} (host=${host})`,
-      )
-      console.info(`[cli] utility supervisor: ${supervisorPath}`)
-      console.info(`[cli] shell command: ${shellCommand.command} ${shellCommand.args.join(" ")}`)
+    const spawnDetails = supportsUserShell()
+      ? buildUserShellCommand(`ELECTRON_RUN_AS_NODE=1 exec ${this.buildCommand(cliEntry, args)}`)
+      : this.buildDirectSpawn(cliEntry, args)
 
-      child = utilityProcess.fork(supervisorPath, [supervisorPayload], {
-        env: { ...shellEnv, ELECTRON_RUN_AS_NODE: "1" },
-        stdio: "pipe",
-        serviceName: "CodeNomad CLI Supervisor",
-      })
-      this.childLaunchMode = "utility"
-    } else {
-      console.info(
-        `[cli] launching CodeNomad CLI (${options.dev ? "dev" : "prod"}) using ${cliEntry.runner} at ${cliEntry.entry} (host=${host})`,
-      )
+    const child = spawn(spawnDetails.command, spawnDetails.args, {
+      cwd: process.cwd(),
+      stdio: ["pipe", "pipe", "pipe"],
+      env,
+      shell: false,
+      detached: process.platform !== "win32",
+    })
 
-      const env = supportsUserShell() ? getUserShellEnv() : { ...process.env }
-      env.ELECTRON_RUN_AS_NODE = "1"
-
-      const spawnDetails = supportsUserShell()
-        ? buildUserShellCommand(`ELECTRON_RUN_AS_NODE=1 exec ${this.buildCommand(cliEntry, args)}`)
-        : this.buildDirectSpawn(cliEntry, args)
-
-      const detached = process.platform !== "win32"
-      child = spawn(spawnDetails.command, spawnDetails.args, {
-        cwd: process.cwd(),
-        stdio: ["ignore", "pipe", "pipe"],
-        env,
-        shell: false,
-        detached,
-      })
-
-      console.info(`[cli] spawn command: ${spawnDetails.command} ${spawnDetails.args.join(" ")}`)
-      this.childLaunchMode = "spawn"
-    }
-
-    if (this.childLaunchMode === "spawn" && !child.pid) {
+    console.info(`[cli] spawn command: ${spawnDetails.command} ${spawnDetails.args.join(" ")}`)
+    if (!child.pid) {
       console.error("[cli] spawn failed: no pid")
     }
 
     this.child = child
+    this.childStartIdentity = child.pid ? getProcessStartIdentityAsync(child.pid, 1_500) : Promise.resolve(undefined)
     this.updateStatus({ pid: child.pid ?? undefined })
 
     const stdout = child.stdout as NodeJS.ReadableStream | undefined
@@ -223,48 +226,25 @@ export class CliProcessManager extends EventEmitter {
       this.handleStream(data.toString(), "stderr")
     })
 
-    if (this.childLaunchMode === "utility") {
-      const utilityChild = child as UtilityProcess
+    child.on("error", (error) => {
+      console.error("[cli] failed to start CLI:", error)
+      this.updateStatus({ state: "error", error: error.message })
+      this.emit("error", error)
+    })
 
-      utilityChild.on("error", (error) => {
-        const message = this.describeUtilityProcessError(error)
-        console.error("[cli] utility supervisor failed:", error)
-        this.updateStatus({ state: "error", error: message })
-        this.emit("error", new Error(message))
-      })
-
-      utilityChild.on("exit", (code) => {
-        const failed = this.status.state !== "ready"
-        const error = failed ? this.status.error ?? `CLI exited with code ${code ?? 0}` : undefined
-        console.info(`[cli] exit (code=${code ?? ""})${error ? ` error=${error}` : ""}`)
-        this.updateStatus({ state: failed ? "error" : "stopped", error })
-        if (failed && error) {
-          this.emit("error", new Error(error))
-        }
-        this.emit("exit", this.status)
-        this.child = undefined
-      })
-    } else {
-      const spawnedChild = child as ChildProcess
-
-      spawnedChild.on("error", (error) => {
-        console.error("[cli] failed to start CLI:", error)
-        this.updateStatus({ state: "error", error: error.message })
-        this.emit("error", error)
-      })
-
-      spawnedChild.on("exit", (code, signal) => {
-        const failed = this.status.state !== "ready"
-        const error = failed ? this.status.error ?? `CLI exited with code ${code ?? 0}${signal ? ` (${signal})` : ""}` : undefined
-        console.info(`[cli] exit (code=${code}, signal=${signal || ""})${error ? ` error=${error}` : ""}`)
-        this.updateStatus({ state: failed ? "error" : "stopped", error })
-        if (failed && error) {
-          this.emit("error", new Error(error))
-        }
-        this.emit("exit", this.status)
-        this.child = undefined
-      })
-    }
+    child.on("exit", (code, signal) => {
+      if (this.child !== child) return
+      const failed = this.status.state !== "ready"
+      const error = failed ? this.status.error ?? `CLI exited with code ${code ?? 0}${signal ? ` (${signal})` : ""}` : undefined
+      console.info(`[cli] exit (code=${code}, signal=${signal || ""})${error ? ` error=${error}` : ""}`)
+      this.updateStatus({ state: failed ? "error" : "stopped", error })
+      if (failed && error) {
+        this.emit("error", new Error(error))
+      }
+      this.emit("exit", this.status)
+      this.child = undefined
+      this.childStartIdentity = undefined
+    })
 
     return new Promise<CliStatus>((resolve, reject) => {
       const timeout = setTimeout(() => {
@@ -284,18 +264,14 @@ export class CliProcessManager extends EventEmitter {
     })
   }
 
-  async stop(): Promise<void> {
+  private async stopNow(): Promise<void> {
     const child = this.child
     if (!child) {
       this.updateStatus({ state: "stopped" })
       return
     }
 
-    if (this.childLaunchMode === "utility") {
-      return this.stopUtilityChild(child as UtilityProcess)
-    }
-
-    const spawnedChild = child as ChildProcess
+    const spawnedChild = child
 
     this.requestedStop = true
 
@@ -308,138 +284,64 @@ export class CliProcessManager extends EventEmitter {
 
     const isAlreadyExited = () => spawnedChild.exitCode !== null || spawnedChild.signalCode !== null
 
-    const tryKillPosixGroup = (signal: NodeJS.Signals) => {
-      try {
-        // Negative PID targets the process group (POSIX).
-        process.kill(-pid, signal)
-        return true
-      } catch (error) {
-        const err = error as NodeJS.ErrnoException
-        if (err?.code === "ESRCH") {
-          return true
-        }
-        return false
-      }
+    const deadlineAt = Date.now() + CLI_STOP_DEADLINE_MS
+    const spawnedIdentity = this.childStartIdentity ?? Promise.resolve(undefined)
+    const { tree: initialCapture, rootStartIdentity } = await captureInitialProcessTree(
+      pid,
+      process.platform,
+      undefined,
+      () => spawnedIdentity,
+      deadlineAt,
+    )
+    let processTree = rootStartIdentity
+      ? mergeCapturedProcessTrees(undefined, initialCapture, pid, rootStartIdentity)
+      : initialCapture
+    let enforcement: Promise<boolean> | null = null
+    const forceProcessTree = (enforcementDeadline = deadlineAt) => {
+      if (enforcement) return enforcement
+      enforcement = (async () => {
+        const latest = await captureProcessTree(pid, process.platform, undefined, Math.min(1_500, enforcementDeadline - Date.now()))
+        processTree = mergeCapturedProcessTrees(processTree, latest, pid, rootStartIdentity)
+        return processTree ? forceCapturedProcessTree(processTree, undefined, undefined, process.kill, { deadlineAt: enforcementDeadline }) : false
+      })().finally(() => { enforcement = null })
+      return enforcement
     }
 
-    const tryKillSinglePid = (signal: NodeJS.Signals) => {
-      try {
-        process.kill(pid, signal)
-        return true
-      } catch (error) {
-        const err = error as NodeJS.ErrnoException
-        if (err?.code === "ESRCH") {
-          return true
-        }
-        return false
-      }
-    }
-
-    const tryTaskkill = (force: boolean) => {
-      const args = ["/PID", String(pid), "/T"]
-      if (force) {
-        args.push("/F")
-      }
-
-      try {
-        const result = spawnSync("taskkill", args, { encoding: "utf8" })
-        const exitCode = result.status
-        if (exitCode === 0) {
-          return true
-        }
-
-        // If the PID is already gone, treat it as success.
-        const stderr = (result.stderr ?? "").toString().toLowerCase()
-        const stdout = (result.stdout ?? "").toString().toLowerCase()
-        const combined = `${stdout}\n${stderr}`
-        if (combined.includes("not found") || combined.includes("no running instance")) {
-          return true
-        }
-        return false
-      } catch {
-        return false
-      }
-    }
-
-    const sendStopSignal = (signal: NodeJS.Signals) => {
-      if (process.platform === "win32") {
-        tryTaskkill(signal === "SIGKILL")
-        return
-      }
-
-      // Prefer process-group signaling so wrapper launchers (shell/tsx) don't outlive Electron.
-      const groupOk = tryKillPosixGroup(signal)
-      if (!groupOk) {
-        tryKillSinglePid(signal)
-      }
-    }
-
-    return new Promise((resolve) => {
-      const killTimeout = setTimeout(() => {
-        console.warn(
-          `[cli] stop timed out after 30000ms; sending SIGKILL (pid=${child.pid ?? "unknown"})`,
-        )
-        sendStopSignal("SIGKILL")
-      }, 30000)
-
-      spawnedChild.on("exit", () => {
-        clearTimeout(killTimeout)
-        this.child = undefined
-        console.info("[cli] CLI process exited")
-        this.updateStatus({ state: "stopped" })
-        resolve()
+    let forceConfirmed = false
+    const enforceIncompleteCleanup = () => {
+      void forceProcessTree().then((confirmed) => {
+        forceConfirmed = confirmed
+        if (!confirmed) console.warn(`[cli] immediate enforcement after incomplete cleanup was not confirmed (pid=${pid})`)
+      }, (error) => {
+        console.warn(`[cli] immediate enforcement after incomplete cleanup failed (pid=${pid})`, error)
+        forceConfirmed = false
       })
+    }
+    this.once("shutdownIncomplete", enforceIncompleteCleanup)
 
-      if (isAlreadyExited()) {
-        clearTimeout(killTimeout)
-        this.child = undefined
-        this.updateStatus({ state: "stopped" })
-        resolve()
-        return
-      }
-
-      sendStopSignal("SIGTERM")
-    })
-  }
-
-  private stopUtilityChild(child: UtilityProcess): Promise<void> {
-    this.requestedStop = true
-
-    const pid = child.pid
-    if (!pid) {
+    try {
+      await stopManagedChild({
+        child: spawnedChild,
+        isExited: isAlreadyExited,
+        force: async (forceDeadline) => forceConfirmed || await forceProcessTree(forceDeadline),
+        isCleanupComplete: () => this.shutdownStatus === "complete",
+        deadlineMs: CLI_STOP_DEADLINE_MS,
+        deadlineAt,
+        forceReserveMs: 5_000,
+        warn: (message, error) => console.warn(`[cli] ${message} (pid=${pid})`, error ?? ""),
+      })
+    } finally {
+      this.off("shutdownIncomplete", enforceIncompleteCleanup)
+    }
+    if (this.shutdownStatus !== "complete") {
+      console.warn(`[cli] CLI exited without a complete graceful-shutdown handshake (status=${this.shutdownStatus ?? "missing"})`)
+    }
+    console.info("[cli] CLI process exited")
+    if (this.child === spawnedChild) {
       this.child = undefined
+      this.childStartIdentity = undefined
       this.updateStatus({ state: "stopped" })
-      return Promise.resolve()
     }
-
-    return new Promise((resolve) => {
-      const killTimeout = setTimeout(() => {
-        console.warn(`[cli] stop timed out after 30000ms; sending SIGKILL (pid=${pid})`)
-        try {
-          process.kill(pid, "SIGKILL")
-        } catch {
-          // no-op
-        }
-      }, 30000)
-
-      child.once("exit", () => {
-        clearTimeout(killTimeout)
-        this.child = undefined
-        console.info("[cli] CLI process exited")
-        this.updateStatus({ state: "stopped" })
-        resolve()
-      })
-
-      if (child.pid === undefined) {
-        clearTimeout(killTimeout)
-        this.child = undefined
-        this.updateStatus({ state: "stopped" })
-        resolve()
-        return
-      }
-
-      child.kill()
-    })
   }
 
   getStatus(): CliStatus {
@@ -455,26 +357,23 @@ export class CliProcessManager extends EventEmitter {
   }
 
   private handleTimeout() {
-    if (this.child) {
-      const pid = this.child.pid
-      if (this.childLaunchMode === "utility") {
-        if (pid) {
-          try {
-            process.kill(pid, "SIGKILL")
-          } catch {
-            // no-op
+    const timedOutChild = this.child
+    if (timedOutChild) {
+      const pid = timedOutChild.pid
+      if (pid) {
+        const deadlineAt = Date.now() + 5_000
+        const spawnedIdentity = this.childStartIdentity ?? Promise.resolve(undefined)
+        void captureInitialProcessTree(pid, process.platform, undefined, () => spawnedIdentity, deadlineAt).then(async ({ tree, rootStartIdentity }) => {
+          const latest = await captureProcessTree(pid, process.platform, undefined, Math.min(1_500, deadlineAt - Date.now()))
+          const processTree = mergeCapturedProcessTrees(tree, latest, pid, rootStartIdentity)
+          const forced = processTree ? await forceCapturedProcessTree(processTree, undefined, undefined, process.kill, { deadlineAt }) : false
+          if (!forced) console.warn(`[cli] startup-timeout process tree cleanup was not confirmed (pid=${pid})`)
+          else if (this.child === timedOutChild) {
+            this.child = undefined
+            this.childStartIdentity = undefined
           }
-        }
-      } else if (pid && process.platform !== "win32") {
-        try {
-          process.kill(-pid, "SIGKILL")
-        } catch {
-          ;(this.child as ChildProcess).kill("SIGKILL")
-        }
-      } else {
-        ;(this.child as ChildProcess).kill("SIGKILL")
+        }).catch((error) => console.warn(`[cli] startup-timeout process tree cleanup failed (pid=${pid})`, error))
       }
-      this.child = undefined
     }
     this.updateStatus({ state: "error", error: "CLI did not start in time" })
     this.emit("error", new Error("CLI did not start in time"))
@@ -505,6 +404,19 @@ export class CliProcessManager extends EventEmitter {
       const trimmed = line.trim()
       if (!trimmed) continue
 
+      if (trimmed === SERVER_SHUTDOWN_COMPLETE) {
+        if (this.shutdownStatus === "incomplete") continue
+        this.shutdownStatus = "complete"
+        console.info("[cli] server confirmed graceful shutdown")
+        continue
+      }
+      if (trimmed === SERVER_SHUTDOWN_INCOMPLETE) {
+        if (this.shutdownStatus === "incomplete") continue
+        this.shutdownStatus = "incomplete"
+        console.warn("[cli] server reported incomplete cleanup; requesting final process-tree enforcement")
+        this.emit("shutdownIncomplete")
+        continue
+      }
       if (trimmed.startsWith(BOOTSTRAP_TOKEN_PREFIX)) {
         const token = trimmed.slice(BOOTSTRAP_TOKEN_PREFIX.length).trim()
         if (token && !this.bootstrapToken) {
@@ -661,57 +573,4 @@ export class CliProcessManager extends EventEmitter {
     throw new Error("Unable to locate the packaged CodeNomad server entrypoint (dist/bin.js). Rebuild the desktop bundle.")
   }
 
-  private shouldUsePackagedShellSupervisor(options: StartOptions): boolean {
-    return false
-  }
-
-  private resolveCliSupervisorPath(): string {
-    const candidates = [
-      path.join(process.resourcesPath, "cli-supervisor.cjs"),
-      path.join(mainDirname, "../resources/cli-supervisor.cjs"),
-    ]
-
-    for (const candidate of candidates) {
-      if (existsSync(candidate)) {
-        return candidate
-      }
-    }
-
-    throw new Error("Unable to locate CodeNomad CLI supervisor script.")
-  }
-
-  private resolveShellNodeCommand(): string {
-    const configured = process.env.NODE_BINARY?.trim()
-    return configured && configured.length > 0 ? configured : "node"
-  }
-
-  private resolveBundledProdEntry(): string {
-    const candidates = [
-      path.join(process.resourcesPath, "server", "dist", "bin.js"),
-      path.join(mainDirname, "../resources/server/dist/bin.js"),
-    ]
-
-    for (const candidate of candidates) {
-      if (existsSync(candidate)) {
-        return candidate
-      }
-    }
-
-    throw new Error("Unable to locate bundled CodeNomad CLI build in app resources.")
-  }
-
-  private describeUtilityProcessError(error: unknown): string {
-    if (error instanceof Error && error.message) {
-      return error.message
-    }
-
-    if (error && typeof error === "object") {
-      const typed = error as { type?: unknown; location?: unknown }
-      if (typeof typed.type === "string") {
-        return typeof typed.location === "string" ? `${typed.type} at ${typed.location}` : typed.type
-      }
-    }
-
-    return String(error)
-  }
 }
diff --git a/packages/electron-app/electron/main/process-stop.test.ts b/packages/electron-app/electron/main/process-stop.test.ts
new file mode 100644
index 00000000..898a79c3
--- /dev/null
+++ b/packages/electron-app/electron/main/process-stop.test.ts
@@ -0,0 +1,542 @@
+import assert from "node:assert/strict"
+import { spawn } from "node:child_process"
+import { EventEmitter, once } from "node:events"
+import { registerHooks } from "node:module"
+import { setTimeout as delay } from "node:timers/promises"
+import test from "node:test"
+import {
+  CLI_SHUTDOWN_COMMAND,
+  CLI_STOP_DEADLINE_MS,
+  captureProcessTree,
+  forceCapturedProcessTree,
+  mergeCapturedProcessTrees,
+  stopManagedChild,
+} from "./process-stop"
+
+class FakeChild extends EventEmitter {
+  writes: string[] = []
+  exited = false
+  stdin = {
+    writable: true,
+    destroyed: false,
+    end: (chunk: string, callback: (error?: Error | null) => void) => {
+      this.writes.push(chunk)
+      callback()
+    },
+  }
+}
+
+test("force success terminates stop without requiring an exit event", async () => {
+  const child = new FakeChild()
+  let forces = 0
+  let resolved = false
+  const stopped = stopManagedChild({
+    child,
+    isExited: () => child.exited,
+    deadlineMs: 100,
+    forceReserveMs: 80,
+    force: () => { forces++; return true },
+  }).then(() => { resolved = true })
+
+  assert.equal(CLI_STOP_DEADLINE_MS, 30_000)
+  assert.deepEqual(child.writes, [CLI_SHUTDOWN_COMMAND])
+  await delay(50)
+  assert.equal(forces, 1)
+  await stopped
+  assert.equal(resolved, true)
+})
+
+test("an absolute stop deadline includes work completed before stopManagedChild starts", async () => {
+  const child = new FakeChild()
+  const deadlineAt = Date.now() + 500
+  await delay(100)
+  const started = Date.now()
+
+  await stopManagedChild({
+    child,
+    isExited: () => false,
+    deadlineMs: 1_000,
+    deadlineAt,
+    forceReserveMs: 200,
+    force: () => true,
+  })
+
+  assert.ok(Date.now() - started < 800)
+})
+
+test("the hard stop deadline rejects even when force never settles", { timeout: 500 }, async () => {
+  const child = new FakeChild()
+  const started = Date.now()
+
+  await assert.rejects(stopManagedChild({
+    child,
+    isExited: () => false,
+    deadlineMs: 30,
+    forceReserveMs: 20,
+    force: () => new Promise<boolean>(() => {}),
+  }), /overall deadline/)
+  assert.ok(Date.now() - started < 100)
+})
+
+test("the hard deadline also bounds enforcement for an already-exited child", { timeout: 500 }, async () => {
+  const child = new FakeChild()
+  child.exited = true
+
+  await assert.rejects(stopManagedChild({
+    child,
+    isExited: () => true,
+    isCleanupComplete: () => false,
+    deadlineMs: 20,
+    force: () => new Promise<boolean>(() => {}),
+  }), /overall deadline/)
+})
+
+test("confirmed exit cancels the delayed force command", async () => {
+  const child = new FakeChild()
+  let forces = 0
+  const stopped = stopManagedChild({
+    child,
+    isExited: () => child.exited,
+    deadlineMs: 15,
+    force: () => { forces++; return true },
+  })
+
+  child.exited = true
+  child.emit("exit")
+  await stopped
+  await delay(30)
+  assert.equal(forces, 0)
+})
+
+test("unconfirmed final enforcement retries until the process exits", async () => {
+  const child = new FakeChild()
+  let forces = 0
+  const stopped = stopManagedChild({
+    child,
+    isExited: () => child.exited,
+    deadlineMs: 100,
+    forceReserveMs: 90,
+    forceRetryMs: 5,
+    force: () => {
+      forces++
+      if (forces < 2) return false
+      child.exited = true
+      child.emit("exit")
+      return true
+    },
+  })
+
+  await stopped
+  assert.equal(forces, 2)
+})
+
+test("exit without a complete shutdown handshake enforces the captured tree", async () => {
+  const child = new FakeChild()
+  let forces = 0
+  const stopped = stopManagedChild({
+    child,
+    isExited: () => child.exited,
+    isCleanupComplete: () => false,
+    force: () => { forces++; return true },
+  })
+
+  child.exited = true
+  child.emit("exit")
+  await stopped
+  assert.equal(forces, 1)
+})
+
+test("ending CLI stdin permits a real child to exit naturally", { timeout: 5_000 }, async () => {
+  const child = spawn(process.execPath, ["-e", `
+    let buffer = ""
+    process.stdin.on("data", (chunk) => {
+      buffer += chunk
+      if (!buffer.includes(${JSON.stringify(CLI_SHUTDOWN_COMMAND.trim())})) return
+      process.stdin.removeAllListeners("data")
+      process.stdin.pause()
+      setTimeout(() => { process.exitCode = 0 }, 10)
+    })
+  `], { stdio: ["pipe", "ignore", "inherit"] })
+  let forces = 0
+
+  await stopManagedChild({
+    child,
+    isExited: () => child.exitCode !== null || child.signalCode !== null,
+    deadlineMs: 1_000,
+    force: () => { forces++; child.kill("SIGKILL"); return true },
+  })
+
+  assert.equal(child.exitCode, 0)
+  assert.equal(forces, 0)
+})
+
+test("tree capture records immutable root and nested descendant identities", async () => {
+  const list = (() => ({ status: 0, stdout: "100|1|linux:boot:10\n200|100|linux:boot:20\n201|200|linux:boot:21\n999|1|linux:boot:99\n", stderr: "", pid: 1,
+    signal: null, output: [] }))
+  const tree = await captureProcessTree(100, "linux", list)
+  assert.deepEqual(tree, { platform: "linux", members: [
+    { pid: 100, startIdentity: "linux:boot:10" },
+    { pid: 200, startIdentity: "linux:boot:20" },
+    { pid: 201, startIdentity: "linux:boot:21" },
+  ] })
+})
+
+test("Windows tree capture ignores the system idle PID without rejecting the process table", async () => {
+  const list = (() => ({
+    status: 0,
+    error: undefined,
+    stdout: "0|0|win32:system\n100|0|win32:100\n101|100|win32:101\n",
+    stderr: "",
+  }))
+  assert.deepEqual((await captureProcessTree(100, "win32", list))?.members, [
+    { pid: 100, startIdentity: "win32:100" },
+    { pid: 101, startIdentity: "win32:101" },
+  ])
+})
+
+test("a malformed descendant row invalidates the entire process snapshot", async () => {
+  const list = (() => ({
+    status: 0,
+    stdout: "100|0|win32:100\n101|100|win32:\n",
+    stderr: "",
+  }))
+
+  assert.equal(await captureProcessTree(100, "win32", list), undefined)
+})
+
+test("Windows verifies creation time and terminates through one native process handle", async () => {
+  const commands: Array<{ command: string; args: readonly string[] }> = []
+  let terminated = false
+  const tree = { platform: "win32" as const, members: [{ pid: 42, startIdentity: "win32:638800000000000000" }] }
+  const runner = async (command: string, args: readonly string[]) => {
+    commands.push({ command, args })
+    terminated = true
+    return { status: 0, stdout: "terminated\n", stderr: "" }
+  }
+  const lookup = async () => {
+    assert.equal(terminated, true, "identity was queried separately before the handle-bound termination")
+    return undefined
+  }
+  const kill = (() => { const error = new Error("gone") as NodeJS.ErrnoException; error.code = "ESRCH"; throw error }) as typeof process.kill
+
+  assert.equal(await forceCapturedProcessTree(tree, lookup, runner, kill), true)
+  assert.equal(commands.length, 1)
+  assert.equal(commands[0]!.command, "powershell.exe")
+  const script = commands[0]!.args.join(" ")
+  assert.match(script, /OpenProcess/)
+  assert.match(script, /GetProcessTimes/)
+  assert.match(script, /TerminateProcess/)
+  assert.match(script, /CloseHandle/)
+  assert.match(script, /638800000000000000/)
+  assert.doesNotMatch(script, /taskkill/i)
+})
+
+test("Windows native-handle termination refuses a live process with a mismatched creation time", {
+  skip: process.platform !== "win32",
+  timeout: 5_000,
+}, async () => {
+  const tree = { platform: "win32" as const, members: [{ pid: process.pid, startIdentity: "win32:1" }] }
+
+  assert.equal(await forceCapturedProcessTree(tree), true)
+  assert.doesNotThrow(() => process.kill(process.pid, 0))
+})
+
+test("Windows native-handle termination accepts CIM precision for an owned process", {
+  skip: process.platform !== "win32",
+  timeout: 10_000,
+}, async (t) => {
+  const child = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], { stdio: "ignore" })
+  t.after(() => { if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL") })
+  assert.ok(child.pid)
+  const exited = once(child, "exit")
+  const tree = await captureProcessTree(child.pid, "win32")
+  assert.ok(tree)
+
+  assert.equal(await forceCapturedProcessTree(tree), true)
+  await exited
+})
+
+test("Windows native-handle termination refuses a sub-microsecond identity mismatch", {
+  skip: process.platform !== "win32",
+  timeout: 10_000,
+}, async (t) => {
+  const child = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], { stdio: "ignore" })
+  t.after(() => { if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL") })
+  assert.ok(child.pid)
+  const tree = await captureProcessTree(child.pid, "win32")
+  assert.ok(tree)
+  tree.members[0]!.startIdentity = `win32:${BigInt(tree.members[0]!.startIdentity.slice(6)) + 1n}`
+
+  assert.equal(await forceCapturedProcessTree(tree), true)
+  assert.doesNotThrow(() => process.kill(child.pid!, 0))
+})
+
+test("PID reuse is identity-guarded on Windows and POSIX", async () => {
+  for (const platform of ["win32", "linux"] as const) {
+    const commands: string[][] = []
+    const signals: number[] = []
+    const tree = { platform, members: [{ pid: 42, startIdentity: platform === "win32" ? "win32:1" : "old" }] }
+    const runTaskkill = ((_command: string, args: readonly string[]) => {
+      commands.push([...args])
+      return { status: 0, stdout: "mismatch\n", stderr: "", pid: 1, signal: null, output: [] }
+    })
+    const kill = ((pid: number) => { signals.push(pid); return true }) as typeof process.kill
+
+    assert.equal(await forceCapturedProcessTree(tree, () => "reused", runTaskkill, kill), true)
+    assert.equal(commands.length, platform === "win32" ? 1 : 0)
+    assert.deepEqual(signals, [])
+  }
+})
+
+test("a stale captured identity cannot authorize termination after handle-bound PID reuse", async () => {
+  let commands = 0
+  const tree = { platform: "win32" as const, members: [{ pid: 42, startIdentity: "win32:1" }] }
+  const runTaskkill = (() => {
+    commands++
+    return { status: 0, stdout: "mismatch\n", stderr: "", pid: 1, signal: null, output: [] }
+  })
+
+  assert.equal(await forceCapturedProcessTree(tree, undefined, runTaskkill, process.kill, {
+    revalidateIdentity: async () => "reused",
+  }), true)
+  assert.equal(commands, 1)
+})
+
+test("a successful snapshot omission still requires a liveness check", async () => {
+  let lookups = 0
+  let livenessChecks = 0
+  const tree = { platform: "win32" as const, members: [{ pid: 42, startIdentity: "win32:1" }] }
+  const runTaskkill = (() => ({ status: 0, stdout: "terminated\n", stderr: "", pid: 1, signal: null, output: [] }))
+  const kill = ((_pid: number, signal?: NodeJS.Signals | number) => {
+    if (signal === 0) livenessChecks++
+    return true
+  }) as typeof process.kill
+
+  assert.equal(await forceCapturedProcessTree(
+    tree,
+    () => { lookups++; return undefined },
+    runTaskkill,
+    kill,
+  ), false)
+  assert.equal(lookups, 1)
+  assert.equal(livenessChecks, 1)
+})
+
+test("enforcement awaits asynchronous commands without blocking timers", async () => {
+  let settled = false
+  let timerFired = false
+  const tree = { platform: "win32" as const, members: [{ pid: 42, startIdentity: "win32:1" }] }
+  const enforcement = Promise.resolve(forceCapturedProcessTree(
+    tree,
+    async () => undefined,
+    (async () => {
+      await delay(30)
+      return { status: 0, stdout: "terminated\n", stderr: "", pid: 1, signal: null, output: [] }
+    }),
+    (() => { const error = new Error("gone") as NodeJS.ErrnoException; error.code = "ESRCH"; throw error }) as typeof process.kill,
+  )).then((value) => { settled = true; return value })
+  setTimeout(() => { timerFired = true }, 1)
+
+  await delay(5)
+  assert.equal(timerFired, true)
+  assert.equal(settled, false)
+  assert.equal(await enforcement, true)
+})
+
+test("failed initial capture retains a bounded spawn-time root identity", async () => {
+  const module = await import("./process-stop") as typeof import("./process-stop") & {
+    captureInitialProcessTree(...args: unknown[]): Promise<{ tree?: unknown; rootStartIdentity?: string }>
+  }
+  const timeouts: number[] = []
+  let lookupStarted = false
+  const result = await module.captureInitialProcessTree(
+    100,
+    "win32",
+    async () => {
+      assert.equal(lookupStarted, true)
+      return { status: 1, stdout: "", stderr: "" }
+    },
+    async (_pid: number, timeoutMs: number) => { lookupStarted = true; timeouts.push(timeoutMs); return "win32:100" },
+    Date.now() + 500,
+  )
+
+  assert.equal(result.rootStartIdentity, "win32:100")
+  assert.ok(timeouts[0]! > 0 && timeouts[0]! <= 500)
+  assert.deepEqual(mergeCapturedProcessTrees(undefined, {
+    platform: "win32",
+    members: [{ pid: 100, startIdentity: "win32:100" }],
+  }, 100, result.rootStartIdentity), {
+    platform: "win32",
+    members: [{ pid: 100, startIdentity: "win32:100" }],
+  })
+})
+
+test("tree enforcement stops launching commands when its deadline is spent", async () => {
+  const tree = { platform: "win32" as const, members: [
+    { pid: 101, startIdentity: "win32:1" },
+    { pid: 102, startIdentity: "win32:2" },
+    { pid: 103, startIdentity: "win32:3" },
+  ] }
+  const timeouts: number[] = []
+  let now = 0
+  const runTaskkill = ((_command: string, _args: readonly string[], options: { timeout?: number }) => {
+    timeouts.push(options.timeout ?? 0)
+    now += options.timeout ?? 0
+    return { status: 0, stdout: "terminated\n", stderr: "", pid: 1, signal: null, output: [] }
+  })
+
+  assert.equal(await forceCapturedProcessTree(tree, undefined, runTaskkill, process.kill, {
+    deadlineAt: 2_500,
+    now: () => now,
+  }), false)
+  assert.deepEqual(timeouts, [1_500, 1_000])
+})
+
+test("later captures preserve root ownership and add every descendant identity", async () => {
+  const captured = { platform: "linux" as const, members: [
+    { pid: 100, startIdentity: "root" },
+    { pid: 200, startIdentity: "old-child" },
+  ] }
+  const latest = { platform: "linux" as const, members: [
+    { pid: 100, startIdentity: "root" },
+    { pid: 200, startIdentity: "reused-child" },
+    { pid: 300, startIdentity: "new-child" },
+  ] }
+
+  const merged = mergeCapturedProcessTrees(captured, latest, 100)!
+  assert.deepEqual(merged.members, [
+    { pid: 100, startIdentity: "root" },
+    { pid: 200, startIdentity: "old-child" },
+    { pid: 200, startIdentity: "reused-child" },
+    { pid: 300, startIdentity: "new-child" },
+  ])
+  const identities = new Map([[100, "root"], [200, "reused-child"], [300, "new-child"]])
+  const signals: number[] = []
+  const kill = ((pid: number, signal?: NodeJS.Signals | number) => {
+    if (signal === 0) {
+      if (identities.has(pid)) return true
+      const error = new Error("gone") as NodeJS.ErrnoException
+      error.code = "ESRCH"
+      throw error
+    }
+    signals.push(pid)
+    identities.delete(pid)
+    return true
+  }) as typeof process.kill
+  assert.equal(await forceCapturedProcessTree(merged, (pid) => identities.get(pid), undefined, kill), true)
+  assert.deepEqual(signals, [300, 200, 100])
+
+  const survivingIdentities = new Map([[100, "root"], [200, "reused-child"], [300, "new-child"]])
+  assert.equal(await forceCapturedProcessTree(
+    merged,
+    (pid) => survivingIdentities.get(pid),
+    undefined,
+    (() => true) as typeof process.kill,
+  ), false)
+
+  const reusedRoot = mergeCapturedProcessTrees(captured, {
+    platform: "linux",
+    members: [{ pid: 100, startIdentity: "reused-root" }, { pid: 400, startIdentity: "foreign-child" }],
+  }, 100)
+  assert.deepEqual(reusedRoot, captured)
+  const rootSignals: number[] = []
+  assert.equal(await forceCapturedProcessTree(
+    reusedRoot!,
+    (pid) => pid === 100 ? "reused-root" : undefined,
+    undefined,
+    ((pid: number, signal?: NodeJS.Signals | number) => {
+      if (signal === 0) {
+        const error = new Error("gone") as NodeJS.ErrnoException
+        error.code = "ESRCH"
+        throw error
+      }
+      rootSignals.push(pid)
+      return true
+    }) as typeof process.kill,
+  ), true)
+  assert.deepEqual(rootSignals, [])
+  assert.equal(mergeCapturedProcessTrees(undefined, latest, 100), undefined)
+})
+
+test("a matching late capture becomes the baseline after the initial capture fails", () => {
+  const latest = { platform: "linux" as const, members: [
+    { pid: 100, startIdentity: "original-root" },
+    { pid: 200, startIdentity: "child" },
+  ] }
+
+  assert.deepEqual(mergeCapturedProcessTrees(undefined, latest, 100, "original-root"), latest)
+  assert.equal(mergeCapturedProcessTrees(undefined, latest, 100, "reused-root"), undefined)
+})
+
+test("an exited root without a trustworthy capture cannot confirm containment", async () => {
+  const child = new FakeChild()
+  child.exited = true
+  let tree: ReturnType<typeof mergeCapturedProcessTrees>
+
+  await assert.rejects(stopManagedChild({
+    child,
+    isExited: () => child.exited,
+    isCleanupComplete: () => false,
+    forceAttempts: 1,
+    force: () => {
+      tree = mergeCapturedProcessTrees(tree, undefined, 100, "original-root")
+      return tree ? forceCapturedProcessTree(tree) : false
+    },
+  }), /termination was not confirmed/)
+})
+
+test("captured descendants are forced individually in child-first order", async () => {
+  const signals: number[] = []
+  const tree = { platform: "linux" as const, members: [
+    { pid: 100, startIdentity: "a" }, { pid: 200, startIdentity: "b" }, { pid: 201, startIdentity: "c" },
+  ] }
+  const identities = new Map([[100, "a"], [200, "b"], [201, "c"]])
+  const kill = ((pid: number, signal?: NodeJS.Signals | number) => {
+    if (signal === 0) {
+      if (identities.has(pid)) return true
+      const error = new Error("gone") as NodeJS.ErrnoException
+      error.code = "ESRCH"
+      throw error
+    }
+    signals.push(pid)
+    identities.delete(pid)
+    return true
+  }) as typeof process.kill
+
+  assert.equal(await forceCapturedProcessTree(tree, (pid) => identities.get(pid), undefined, kill), true)
+  assert.deepEqual(signals, [201, 200, 100])
+})
+
+test("signal dispatch is not confirmation while the captured identity remains", async () => {
+  const tree = { platform: "linux" as const, members: [{ pid: 42, startIdentity: "owned" }] }
+  const kill = (() => true) as typeof process.kill
+
+  assert.equal(await forceCapturedProcessTree(tree, () => "owned", undefined, kill), false)
+})
+
+test("incomplete shutdown status remains terminal", async () => {
+  const hooks = registerHooks({
+    resolve(specifier, context, nextResolve) {
+      if (specifier === "electron") {
+        return { shortCircuit: true, url: "data:text/javascript,export const app={isPackaged:false,getAppPath(){return ''}}" }
+      }
+      return nextResolve(specifier, context)
+    },
+  })
+  try {
+    const { CliProcessManager } = await import("./process-manager")
+    const manager = new CliProcessManager()
+    let enforcements = 0
+    ;(manager as EventEmitter).on("shutdownIncomplete", () => { enforcements++ })
+
+    ;(manager as any).handleStream(
+      "CODENOMAD_SHUTDOWN_STATUS:incomplete\nCODENOMAD_SHUTDOWN_STATUS:complete\n",
+      "stdout",
+    )
+
+    assert.equal((manager as any).shutdownStatus, "incomplete")
+    assert.equal(enforcements, 1)
+  } finally {
+    hooks.deregister()
+  }
+})
diff --git a/packages/electron-app/electron/main/process-stop.ts b/packages/electron-app/electron/main/process-stop.ts
new file mode 100644
index 00000000..658bd7e8
--- /dev/null
+++ b/packages/electron-app/electron/main/process-stop.ts
@@ -0,0 +1,361 @@
+import { execFile } from "node:child_process"
+import { getProcessStartIdentityAsync, type AsyncProcessStartIdentityLookup } from "./client-state-process-identity"
+
+export const CLI_SHUTDOWN_COMMAND = "codenomad:shutdown\n"
+export const CLI_STOP_DEADLINE_MS = 30_000
+
+interface ExitTrackedChild {
+  stdin?: {
+    destroyed?: boolean
+    writable?: boolean
+    end(chunk: string, callback: (error?: Error | null) => void): unknown
+  } | null
+  once(event: "exit", listener: () => void): unknown
+  off?(event: "exit", listener: () => void): unknown
+}
+
+interface StopManagedChildOptions {
+  child: ExitTrackedChild
+  isExited(): boolean
+  force(deadlineAt?: number): Promise<boolean> | boolean
+  isCleanupComplete?(): boolean
+  deadlineMs?: number
+  deadlineAt?: number
+  forceReserveMs?: number
+  forceRetryMs?: number
+  forceAttempts?: number
+  warn?(message: string, error?: unknown): void
+}
+
+interface ProcessRow {
+  pid: number
+  parentPid: number
+  startIdentity: string
+}
+
+export interface CapturedProcessTree {
+  platform: NodeJS.Platform
+  members: Array<{ pid: number; startIdentity: string }>
+}
+
+interface AsyncCommandResult {
+  status: number | null
+  stdout: string
+  stderr: string
+  error?: Error
+}
+
+type AsyncCommandRunner = (
+  command: string,
+  args: readonly string[],
+  options: { encoding: "utf8"; timeout: number; windowsHide?: boolean; env?: NodeJS.ProcessEnv },
+) => Promise<AsyncCommandResult> | AsyncCommandResult
+
+interface ForceCapturedProcessTreeOptions {
+  deadlineAt?: number
+  now?: () => number
+  revalidateIdentity?: AsyncProcessStartIdentityLookup
+}
+
+export function mergeCapturedProcessTrees(
+  captured: CapturedProcessTree | undefined,
+  latest: CapturedProcessTree | undefined,
+  rootPid: number,
+  expectedRootIdentity?: string,
+): CapturedProcessTree | undefined {
+  if (!latest || (captured && latest.platform !== captured.platform)) return captured
+  const capturedRoot = captured?.members.find((member) => member.pid === rootPid)
+  const latestRoot = latest.members.find((member) => member.pid === rootPid)
+  const rootIdentity = capturedRoot?.startIdentity ?? expectedRootIdentity
+  if (!rootIdentity || !latestRoot || rootIdentity !== latestRoot.startIdentity) return captured
+  if (!captured) return latest
+
+  const identityKey = (member: { pid: number; startIdentity: string }) => `${member.pid}\0${member.startIdentity}`
+  const members = new Map(captured.members.map((member) => [identityKey(member), member]))
+  for (const member of latest.members) {
+    members.set(identityKey(member), member)
+  }
+  return { platform: captured.platform, members: [...members.values()] }
+}
+
+function runCommand(
+  command: string,
+  args: readonly string[],
+  options: { encoding: "utf8"; timeout: number; windowsHide?: boolean; env?: NodeJS.ProcessEnv },
+): Promise<AsyncCommandResult> {
+  return new Promise((resolve) => {
+    execFile(command, args, options, (error, stdout, stderr) => {
+      resolve({ status: error ? null : 0, stdout, stderr, error: error ?? undefined })
+    })
+  })
+}
+
+async function captureProcessRows(
+  platform: NodeJS.Platform,
+  runList: AsyncCommandRunner,
+  timeoutMs: number,
+): Promise<ProcessRow[] | undefined> {
+  if (timeoutMs <= 0) return undefined
+  const result = platform === "win32"
+    ? await runList("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command",
+        "Get-CimInstance Win32_Process | ForEach-Object { '{0}|{1}|win32:{2}' -f $_.ProcessId, $_.ParentProcessId, ([datetime]$_.CreationDate).ToUniversalTime().Ticks }"],
+        { encoding: "utf8", timeout: timeoutMs, windowsHide: true })
+    : platform === "linux"
+      ? await runList("sh", ["-c", `boot=$(cat /proc/sys/kernel/random/boot_id) || exit 1
+for stat in /proc/[0-9]*/stat; do
+  line=$(cat "$stat" 2>/dev/null) || continue
+  pid=$(printf '%s\n' "$line" | cut -d' ' -f1); rest=$(printf '%s\n' "$line" | sed 's/^.*) //'); set -- $rest
+  ppid=$2; shift 19; printf '%s|%s|linux:%s:%s\n' "$pid" "$ppid" "$boot" "$1"
+done`], { encoding: "utf8", timeout: timeoutMs })
+      : await runList("ps", ["-A", "-o", "pid=,ppid=,lstart="], { encoding: "utf8", timeout: timeoutMs,
+          env: { ...process.env, LC_ALL: "C", LANG: "C" } })
+  if (result.status !== 0 || result.error) return undefined
+
+  const rows: ProcessRow[] = []
+  for (const line of String(result.stdout ?? "").split(/\r?\n/)) {
+    if (!line.trim()) continue
+    if (platform === "darwin" ? /^0(?:\s|$)/.test(line.trim()) : /^0(?:\||$)/.test(line.trim())) continue
+    const fields = platform === "darwin"
+      ? line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/)?.slice(1)
+      : line.trim().split("|")
+    if (!fields || fields.length !== 3) return undefined
+    const [pidText, parentPidText, rawIdentity] = fields
+    const pid = Number(pidText), parentPid = Number(parentPidText)
+    const startIdentity = platform === "darwin" ? `darwin:${rawIdentity}` : rawIdentity
+    const validIdentity = platform === "win32"
+      ? /^win32:\d+$/.test(startIdentity)
+      : platform === "linux"
+        ? /^linux:[^:]+:\d+$/.test(startIdentity)
+        : Boolean(rawIdentity.trim())
+    if (!Number.isInteger(pid) || pid <= 0 || !Number.isInteger(parentPid) || !validIdentity) return undefined
+    rows.push({ pid, parentPid, startIdentity })
+  }
+  return rows
+}
+
+function processTreeFromRows(rootPid: number, platform: NodeJS.Platform, rows: ProcessRow[]): CapturedProcessTree | undefined {
+  const descendants = new Set([rootPid])
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const row of rows) {
+      if (!descendants.has(row.parentPid) || descendants.has(row.pid)) continue
+      descendants.add(row.pid)
+      changed = true
+    }
+  }
+  const members = rows.filter((row) => descendants.has(row.pid))
+    .map(({ pid, startIdentity }) => ({ pid, startIdentity }))
+  return members.some((member) => member.pid === rootPid) ? { platform, members } : undefined
+}
+
+export async function captureProcessTree(
+  rootPid: number,
+  platform: NodeJS.Platform = process.platform,
+  runList: AsyncCommandRunner = runCommand,
+  timeoutMs = 1_500,
+): Promise<CapturedProcessTree | undefined> {
+  const rows = await captureProcessRows(platform, runList, timeoutMs)
+  return rows ? processTreeFromRows(rootPid, platform, rows) : undefined
+}
+
+export async function captureInitialProcessTree(
+  rootPid: number,
+  platform: NodeJS.Platform = process.platform,
+  runList: AsyncCommandRunner = runCommand,
+  lookup: AsyncProcessStartIdentityLookup = (pid, timeoutMs) => getProcessStartIdentityAsync(pid, timeoutMs, platform),
+  deadlineAt = Date.now() + 3_000,
+): Promise<{ tree?: CapturedProcessTree; rootStartIdentity?: string }> {
+  const fallbackIdentity = Promise.resolve(lookup(rootPid, Math.min(1_500, deadlineAt - Date.now())))
+  const captured = await captureProcessTree(rootPid, platform, runList, Math.min(1_500, deadlineAt - Date.now()))
+  const rootStartIdentity = await fallbackIdentity
+  const tree = rootStartIdentity
+    ? mergeCapturedProcessTrees(undefined, captured, rootPid, rootStartIdentity)
+    : undefined
+  return { tree, rootStartIdentity }
+}
+
+export async function forceCapturedProcessTree(
+  tree: CapturedProcessTree,
+  lookup?: AsyncProcessStartIdentityLookup,
+  runTerminate: AsyncCommandRunner = runCommand,
+  kill: typeof process.kill = process.kill,
+  options: ForceCapturedProcessTreeOptions = {},
+): Promise<boolean> {
+  const now = options.now ?? Date.now
+  const remainingMs = () => options.deadlineAt === undefined ? 1_500 : options.deadlineAt - now()
+  const currentIdentity = options.revalidateIdentity ?? lookup
+    ?? ((pid, timeoutMs) => getProcessStartIdentityAsync(pid, timeoutMs, tree.platform))
+  let confirmed = true
+  const isGone = (pid: number) => {
+    try {
+      kill(pid, 0)
+      return false
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code === "ESRCH"
+    }
+  }
+  for (const member of [...tree.members].reverse()) {
+    if (remainingMs() <= 0) return false
+    if (tree.platform === "win32") {
+      const expectedTicks = member.startIdentity.match(/^win32:(\d+)$/)?.[1]
+      if (!expectedTicks) {
+        confirmed = false
+        continue
+      }
+      const timeout = Math.min(1_500, remainingMs())
+      if (timeout <= 0) return false
+      const script = `$source = @'
+using System;
+using System.Runtime.InteropServices;
+public static class CodeNomadProcessHandle {
+  [StructLayout(LayoutKind.Sequential)] public struct FileTime { public uint Low; public uint High; }
+  [DllImport("kernel32.dll", SetLastError=true)] public static extern IntPtr OpenProcess(uint access, bool inherit, uint processId);
+  [DllImport("kernel32.dll", SetLastError=true)] public static extern bool GetProcessTimes(IntPtr process, out FileTime creation, out FileTime exit, out FileTime kernel, out FileTime user);
+  [DllImport("kernel32.dll", SetLastError=true)] public static extern bool TerminateProcess(IntPtr process, uint exitCode);
+  [DllImport("kernel32.dll")] public static extern bool CloseHandle(IntPtr handle);
+}
+'@
+Add-Type -TypeDefinition $source
+$handle = [CodeNomadProcessHandle]::OpenProcess(0x1001, $false, ${member.pid})
+if ($handle -eq [IntPtr]::Zero) { exit 3 }
+try {
+  $creation = [CodeNomadProcessHandle+FileTime]::new()
+  $exit = [CodeNomadProcessHandle+FileTime]::new()
+  $kernel = [CodeNomadProcessHandle+FileTime]::new()
+  $user = [CodeNomadProcessHandle+FileTime]::new()
+  if (-not [CodeNomadProcessHandle]::GetProcessTimes($handle, [ref]$creation, [ref]$exit, [ref]$kernel, [ref]$user)) { exit 4 }
+  $fileTime = ([long]$creation.High -shl 32) -bor $creation.Low
+  $nativeTicks = [DateTime]::FromFileTimeUtc($fileTime).Ticks
+  $expectedTicks = [long]::Parse('${expectedTicks}')
+  $nativeTicks -= $nativeTicks % 10
+  if ($nativeTicks -ne $expectedTicks) { 'mismatch'; exit 0 }
+  if (-not [CodeNomadProcessHandle]::TerminateProcess($handle, 1)) { exit 5 }
+  'terminated'
+} finally {
+  [void][CodeNomadProcessHandle]::CloseHandle($handle)
+}`
+      const result = await runTerminate("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+        encoding: "utf8",
+        timeout,
+        windowsHide: true,
+      })
+      const outcome = result.status === 0 ? result.stdout.trim() : ""
+      if (outcome === "mismatch") continue
+      if (outcome !== "terminated" && !isGone(member.pid)) confirmed = false
+      continue
+    }
+    const identity = await currentIdentity(member.pid, Math.min(1_500, remainingMs()))
+    if (!identity) {
+      if (!isGone(member.pid)) confirmed = false
+      continue
+    }
+    if (identity !== member.startIdentity) continue
+    try {
+      kill(member.pid, "SIGKILL")
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ESRCH") confirmed = false
+    }
+  }
+  if (remainingMs() <= 0) return false
+  for (const member of tree.members) {
+    if (remainingMs() <= 0) return false
+    const remainingIdentity = await currentIdentity(member.pid, Math.min(1_500, remainingMs()))
+    if (remainingIdentity === member.startIdentity) confirmed = false
+    else if (!remainingIdentity && !isGone(member.pid)) confirmed = false
+  }
+  return confirmed
+}
+
+export function stopManagedChild(options: StopManagedChildOptions): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let settled = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let hardTimer: ReturnType<typeof setTimeout> | undefined
+    let attempts = 0
+    const deadlineMs = options.deadlineMs ?? CLI_STOP_DEADLINE_MS
+    const deadlineAt = options.deadlineAt ?? Date.now() + deadlineMs
+    const cleanupComplete = options.isCleanupComplete ?? (() => true)
+    const removeListener = () => options.child.off?.("exit", onExit)
+    const finish = (error?: Error) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      if (hardTimer) clearTimeout(hardTimer)
+      removeListener()
+      if (error) reject(error)
+      else resolve()
+    }
+    let forcing = false
+    const force = () => {
+      if (timer) clearTimeout(timer)
+      timer = undefined
+      if (settled) return
+      if (forcing) return
+      if (Date.now() >= deadlineAt) {
+        finish(new Error("CLI process tree termination exceeded its overall deadline"))
+        return
+      }
+      attempts += 1
+      forcing = true
+      void Promise.resolve().then(() => options.force(deadlineAt)).then((confirmed) => {
+        forcing = false
+        if (settled) return
+        if (Date.now() > deadlineAt) {
+          finish(new Error("CLI process tree termination exceeded its overall deadline"))
+          return
+        }
+        if (confirmed) {
+          finish()
+          return
+        }
+        retry()
+      }, (error) => {
+        forcing = false
+        options.warn?.("Failed to force CLI process tree termination", error)
+        retry()
+      })
+    }
+    const retry = () => {
+      const maxAttempts = options.forceAttempts ?? 3
+      if (attempts >= maxAttempts) {
+        finish(new Error(`CLI process tree termination was not confirmed after ${attempts} attempts`))
+        return
+      }
+      options.warn?.("CLI process tree termination was not confirmed; retrying")
+      const retryMs = options.forceRetryMs ?? 1_000
+      timer = setTimeout(force, Math.min(retryMs, Math.max(0, deadlineAt - Date.now())))
+    }
+    function onExit() {
+      if (cleanupComplete()) finish()
+      else force()
+    }
+
+    options.child.once("exit", onExit)
+    hardTimer = setTimeout(() => {
+      finish(new Error("CLI process tree termination exceeded its overall deadline"))
+    }, Math.max(0, deadlineAt - Date.now()))
+    if (options.isExited()) {
+      onExit()
+      return
+    }
+
+    const forceAt = deadlineAt - (options.forceReserveMs ?? Math.min(1_500, deadlineMs / 2))
+    timer = setTimeout(() => {
+      options.warn?.("CLI cleanup reached its final enforcement window; forcing process tree termination")
+      force()
+    }, Math.max(0, forceAt - Date.now()))
+    const stdin = options.child.stdin
+    if (!stdin || stdin.destroyed || stdin.writable === false) {
+      options.warn?.("CLI stdin is not writable; waiting until the force deadline")
+      return
+    }
+    try {
+      stdin.end(CLI_SHUTDOWN_COMMAND, (error) => {
+        if (error) options.warn?.("Failed to send the CLI graceful shutdown command; waiting until the force deadline", error)
+      })
+    } catch (error) {
+      options.warn?.("Failed to send the CLI graceful shutdown command; waiting until the force deadline", error)
+    }
+  })
+}
diff --git a/packages/electron-app/electron/main/renderer-client-state-flush.test.ts b/packages/electron-app/electron/main/renderer-client-state-flush.test.ts
new file mode 100644
index 00000000..3617e4d8
--- /dev/null
+++ b/packages/electron-app/electron/main/renderer-client-state-flush.test.ts
@@ -0,0 +1,25 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import { flushRendererClientStateBeforeShutdown, type RendererFlushWindow } from "./renderer-client-state-flush"
+
+const window = (executeJavaScript: (source: string) => Promise<unknown>): RendererFlushWindow => ({
+  isDestroyed: () => false,
+  webContents: { isDestroyed: () => false, getURL: () => "http://127.0.0.1:3000/app", executeJavaScript },
+})
+
+test("renderer flush enforces primary/trusted access and invokes the registered callback", async () => {
+  let calls = 0
+  let source = ""
+  const target = window(async (value) => { calls++; source = value })
+  assert.equal(await flushRendererClientStateBeforeShutdown(target, false, () => true), "not-primary")
+  assert.equal(await flushRendererClientStateBeforeShutdown(target, true, () => false), "untrusted-origin")
+  assert.equal(calls, 0)
+  assert.equal(await flushRendererClientStateBeforeShutdown(target, true, () => true), "flushed")
+  assert.equal(calls, 1)
+  assert.match(source, /__CODENOMAD_FLUSH_CLIENT_STATE_BEFORE_NATIVE_SHUTDOWN__/)
+  assert.match(source, /http:\/\/127\.0\.0\.1:3000/)
+})
+
+test("renderer flush rejects after its bounded timeout", async () => {
+  await assert.rejects(flushRendererClientStateBeforeShutdown(window(() => new Promise(() => {})), true, () => true, 10), /timed out after 10ms/)
+})
diff --git a/packages/electron-app/electron/main/renderer-client-state-flush.ts b/packages/electron-app/electron/main/renderer-client-state-flush.ts
new file mode 100644
index 00000000..1ab48365
--- /dev/null
+++ b/packages/electron-app/electron/main/renderer-client-state-flush.ts
@@ -0,0 +1,61 @@
+export const RENDERER_CLIENT_STATE_FLUSH_TIMEOUT_MS = 1_000
+
+const RENDERER_CLIENT_STATE_FLUSH_CALLBACK = "__CODENOMAD_FLUSH_CLIENT_STATE_BEFORE_NATIVE_SHUTDOWN__"
+
+interface RendererFlushWebContents {
+  isDestroyed(): boolean
+  getURL(): string
+  executeJavaScript(source: string, userGesture?: boolean): Promise<unknown>
+}
+
+export interface RendererFlushWindow {
+  isDestroyed(): boolean
+  webContents: RendererFlushWebContents
+}
+
+export type RendererFlushResult = "flushed" | "not-primary" | "window-unavailable" | "untrusted-origin"
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`Renderer client-state flush timed out after ${timeoutMs}ms`)),
+      timeoutMs,
+    )
+    promise.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (error) => {
+        clearTimeout(timer)
+        reject(error)
+      },
+    )
+  })
+}
+
+export async function flushRendererClientStateBeforeShutdown(
+  window: RendererFlushWindow | null,
+  isPrimary: boolean,
+  isTrustedOrigin: (url: string) => boolean,
+  timeoutMs = RENDERER_CLIENT_STATE_FLUSH_TIMEOUT_MS,
+): Promise<RendererFlushResult> {
+  if (!isPrimary) return "not-primary"
+  if (!window || window.isDestroyed() || window.webContents.isDestroyed()) return "window-unavailable"
+
+  const currentUrl = window.webContents.getURL()
+  if (!isTrustedOrigin(currentUrl)) return "untrusted-origin"
+
+  const callbackName = JSON.stringify(RENDERER_CLIENT_STATE_FLUSH_CALLBACK)
+  const expectedOrigin = JSON.stringify(new URL(currentUrl).origin)
+  await withTimeout(
+    window.webContents.executeJavaScript(`(() => {
+      if (window.location.origin !== ${expectedOrigin}) throw new Error("Renderer origin changed before client-state flush");
+      const flush = window[${callbackName}];
+      if (typeof flush !== "function") throw new Error("Renderer client-state flush callback is unavailable");
+      return flush();
+    })()`),
+    timeoutMs,
+  )
+  return "flushed"
+}
diff --git a/packages/electron-app/electron/main/renderer-origin.test.ts b/packages/electron-app/electron/main/renderer-origin.test.ts
new file mode 100644
index 00000000..9080e7cc
--- /dev/null
+++ b/packages/electron-app/electron/main/renderer-origin.test.ts
@@ -0,0 +1,25 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import { resolveConfiguredRendererOrigins } from "./renderer-origin"
+
+test("packaged renderer origins exclude development server environment URLs", () => {
+  assert.deepEqual(
+    resolveConfiguredRendererOrigins(
+      "https://127.0.0.1:43123/workspace",
+      true,
+      ["http://localhost:3000/app", "http://127.0.0.1:5173/loading.html"],
+    ),
+    ["https://127.0.0.1:43123"],
+  )
+})
+
+test("development renderer origins include configured development servers", () => {
+  assert.deepEqual(
+    resolveConfiguredRendererOrigins(
+      "http://127.0.0.1:43123/workspace",
+      false,
+      ["http://localhost:3000/app", "http://localhost:3000/loading.html"],
+    ),
+    ["http://127.0.0.1:43123", "http://localhost:3000"],
+  )
+})
diff --git a/packages/electron-app/electron/main/renderer-origin.ts b/packages/electron-app/electron/main/renderer-origin.ts
new file mode 100644
index 00000000..40f501b1
--- /dev/null
+++ b/packages/electron-app/electron/main/renderer-origin.ts
@@ -0,0 +1,24 @@
+export function isAllowedRendererOrigin(origin: string | undefined | null, allowedOrigins: string[]): boolean {
+  if (!origin) return false
+  try {
+    return allowedOrigins.includes(new URL(origin).origin)
+  } catch {
+    return false
+  }
+}
+
+export function resolveConfiguredRendererOrigins(
+  currentCliUrl: string | null,
+  isPackaged: boolean,
+  devCandidates: Array<string | undefined>,
+): string[] {
+  const candidates = isPackaged ? [currentCliUrl] : [currentCliUrl, ...devCandidates]
+  const origins = new Set<string>()
+  for (const candidate of candidates) {
+    if (!candidate) continue
+    try {
+      origins.add(new URL(candidate).origin)
+    } catch {}
+  }
+  return [...origins]
+}
diff --git a/packages/electron-app/electron/main/serialized-lifecycle.test.ts b/packages/electron-app/electron/main/serialized-lifecycle.test.ts
new file mode 100644
index 00000000..24e7422f
--- /dev/null
+++ b/packages/electron-app/electron/main/serialized-lifecycle.test.ts
@@ -0,0 +1,38 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import { SerializedLifecycle } from "./serialized-lifecycle"
+
+test("serializes operations and exposes shutdown before queued work resumes", async () => {
+  const lifecycle = new SerializedLifecycle()
+  let release!: () => void
+  const gate = new Promise<void>((resolve) => { release = resolve })
+  let active = 0, maximum = 0
+  const first = lifecycle.enqueue(async () => {
+    active += 1; maximum = Math.max(maximum, active)
+    await gate
+    active -= 1
+    if (lifecycle.stopped) throw new Error("stopped")
+  })
+  const second = lifecycle.enqueue(async () => {
+    active += 1; maximum = Math.max(maximum, active); active -= 1
+  })
+  const shutdown = lifecycle.stop(async () => {})
+  release()
+  await assert.rejects(first, /stopped/)
+  await second
+  await shutdown
+  assert.equal(maximum, 1)
+})
+
+test("failed shutdown reopens the lifecycle before queued retries run", async () => {
+  const lifecycle = new SerializedLifecycle()
+  const shutdown = lifecycle.stop(async () => { throw new Error("cleanup unconfirmed") })
+  const retry = lifecycle.enqueue(async () => {
+    assert.equal(lifecycle.stopped, false)
+    return "restarted"
+  })
+
+  await assert.rejects(shutdown, /cleanup unconfirmed/)
+  assert.equal(await retry, "restarted")
+  assert.equal(lifecycle.stopped, false)
+})
diff --git a/packages/electron-app/electron/main/serialized-lifecycle.ts b/packages/electron-app/electron/main/serialized-lifecycle.ts
new file mode 100644
index 00000000..1f72f5a7
--- /dev/null
+++ b/packages/electron-app/electron/main/serialized-lifecycle.ts
@@ -0,0 +1,22 @@
+export class SerializedLifecycle {
+  private tail: Promise<void> = Promise.resolve()
+  stopped = false
+
+  enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    const queued = this.tail.catch(() => {}).then(operation)
+    this.tail = queued.then(() => {}, () => {})
+    return queued
+  }
+
+  stop<T>(operation: () => Promise<T>): Promise<T> {
+    this.stopped = true
+    return this.enqueue(async () => {
+      try {
+        return await operation()
+      } catch (error) {
+        this.stopped = false
+        throw error
+      }
+    })
+  }
+}
diff --git a/packages/electron-app/electron/main/window-state.test.ts b/packages/electron-app/electron/main/window-state.test.ts
new file mode 100644
index 00000000..fae89974
--- /dev/null
+++ b/packages/electron-app/electron/main/window-state.test.ts
@@ -0,0 +1,110 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import { clampWindowBounds, installWindowZoomInput, normalizeNativeWindowState, normalizeZoomFactor, restoreWindowState, WindowStateTracker } from "./window-state"
+import type { BrowserWindow } from "electron"
+import type { ClientStateManager } from "./client-state"
+
+const primaryDisplay = { x: 0, y: 0, width: 1920, height: 1080 }
+
+test("normalizes persisted window state", () => {
+  assert.equal(normalizeNativeWindowState({ bounds: { x: 0, y: 0, width: Number.NaN, height: 900 }, maximized: false, fullscreen: false, zoomFactor: 1 }), undefined)
+  assert.deepEqual(clampWindowBounds({ x: 4000, y: 2000, width: 1400, height: 900 }, [primaryDisplay]), { x: 520, y: 180, width: 1400, height: 900 })
+  assert.deepEqual(
+    clampWindowBounds({ x: -2000, y: 100, width: 3000, height: 300 }, [{ x: -1280, y: 0, width: 1280, height: 1024 }, primaryDisplay]),
+    { x: -1280, y: 100, width: 1280, height: 600 },
+  )
+})
+
+test("normalizes unsafe zoom factors", () => {
+  assert.equal(normalizeZoomFactor(Number.POSITIVE_INFINITY), 1)
+  assert.equal(normalizeZoomFactor(0.01), 0.25)
+  assert.equal(normalizeZoomFactor(9), 5)
+})
+
+test("restores shared outer position and content size", () => {
+  const calls: unknown[] = []
+  const window = {
+    setPosition: (x: number, y: number) => calls.push(["position", x, y]),
+    setContentSize: (width: number, height: number) => calls.push(["content", width, height]),
+    maximize: () => undefined,
+    setFullScreen: () => undefined,
+    webContents: { setZoomFactor: () => undefined },
+  } as unknown as BrowserWindow
+  const bounds = { x: 10, y: 20, width: 1200, height: 800 }
+  restoreWindowState(window, { bounds, maximized: false, fullscreen: false, zoomFactor: 1 }, bounds)
+  assert.deepEqual(calls, [["position", 10, 20], ["content", 1200, 800]])
+})
+
+test("flush captures the current native zoom", async () => {
+  let zoomLevel = -0.5
+  const window = {
+    isDestroyed: () => false,
+    on: () => undefined,
+    getPosition: () => [0, 0],
+    getContentSize: () => [1200, 800],
+    isMaximized: () => false,
+    isFullScreen: () => false,
+    webContents: {
+      isDestroyed: () => false,
+      on: () => undefined,
+      setZoomLevel: (level: number) => { zoomLevel = level },
+      getZoomLevel: () => zoomLevel,
+      setZoomFactor: (factor: number) => { zoomLevel = Math.log(factor) / Math.log(1.2) },
+      getZoomFactor: () => 1.2 ** zoomLevel,
+    },
+  } as unknown as BrowserWindow
+  const savedZoomFactors: number[] = []
+  const manager = {
+    saveWindowState: async (state: { zoomFactor: number }) => { savedZoomFactors.push(state.zoomFactor); return true },
+    flush: async () => undefined,
+  } as unknown as ClientStateManager
+  const tracker = new WindowStateTracker(window, manager, { bounds: { x: 0, y: 0, width: 1200, height: 800 }, maximized: false, fullscreen: false, zoomFactor: 1 })
+
+  await tracker.flush()
+  assert.ok(Math.abs(savedZoomFactors.at(-1)! - (1.2 ** -0.5)) < 0.000001)
+})
+
+test("Electron keyboard and wheel zoom input is applied explicitly", () => {
+  const events = new Map<string, (...args: any[]) => void>()
+  let zoomLevel = 0
+  const prevented: string[] = []
+  const window = {
+    webContents: {
+      on: (name: string, handler: (...args: any[]) => void) => events.set(name, handler),
+      getZoomLevel: () => zoomLevel,
+    },
+  } as unknown as BrowserWindow
+  installWindowZoomInput(window, (level) => { zoomLevel = level })
+
+  events.get("before-input-event")?.({ preventDefault: () => prevented.push("keyboard") }, {
+    type: "keyDown", control: true, meta: false, alt: false, key: "=",
+  })
+  assert.equal(zoomLevel, 0.5)
+  events.get("zoom-changed")?.({ preventDefault: () => prevented.push("wheel") }, "out")
+  assert.equal(zoomLevel, 0)
+  assert.deepEqual(prevented, ["keyboard", "wheel"])
+})
+
+test("native menu zoom survives cross-origin navigation", () => {
+  const events = new Map<string, (...args: any[]) => void>()
+  let zoomLevel = -0.5
+  const window = {
+    isDestroyed: () => false,
+    on: () => undefined,
+    webContents: {
+      isDestroyed: () => false,
+      on: (name: string, handler: (...args: any[]) => void) => events.set(name, handler),
+      getZoomFactor: () => 1.2 ** zoomLevel,
+      setZoomFactor: (factor: number) => { zoomLevel = Math.log(factor) / Math.log(1.2) },
+    },
+  } as unknown as BrowserWindow
+  const manager = { flush: async () => undefined } as unknown as ClientStateManager
+  new WindowStateTracker(window, manager, {
+    bounds: { x: 0, y: 0, width: 1200, height: 800 }, maximized: false, fullscreen: false, zoomFactor: 1,
+  })
+
+  events.get("did-start-navigation")?.({}, "http://next.test", false, true)
+  zoomLevel = 0
+  events.get("did-finish-load")?.()
+  assert.ok(Math.abs(zoomLevel - (-0.5)) < 0.000001)
+})
diff --git a/packages/electron-app/electron/main/window-state.ts b/packages/electron-app/electron/main/window-state.ts
new file mode 100644
index 00000000..b595b495
--- /dev/null
+++ b/packages/electron-app/electron/main/window-state.ts
@@ -0,0 +1,252 @@
+import type { BrowserWindow } from "electron"
+import type { ClientStateManager, NativeWindowState, WindowBounds } from "./client-state"
+
+export const DEFAULT_WINDOW_WIDTH = 1400
+export const DEFAULT_WINDOW_HEIGHT = 900
+
+const MIN_WINDOW_WIDTH = 800
+const MIN_WINDOW_HEIGHT = 600
+const MIN_ZOOM_FACTOR = 0.25
+const MAX_ZOOM_FACTOR = 5
+const SAVE_DEBOUNCE_MS = 250
+
+export interface DisplayWorkArea {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value)
+}
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.min(Math.max(value, minimum), maximum)
+}
+
+function intersectionArea(bounds: WindowBounds, area: DisplayWorkArea): number {
+  const width = Math.max(0, Math.min(bounds.x + bounds.width, area.x + area.width) - Math.max(bounds.x, area.x))
+  const height = Math.max(0, Math.min(bounds.y + bounds.height, area.y + area.height) - Math.max(bounds.y, area.y))
+  return width * height
+}
+
+function centerDistanceSquared(bounds: WindowBounds, area: DisplayWorkArea): number {
+  const x = bounds.x + bounds.width / 2 - (area.x + area.width / 2)
+  const y = bounds.y + bounds.height / 2 - (area.y + area.height / 2)
+  return x * x + y * y
+}
+
+export function normalizeZoomFactor(value: unknown): number {
+  if (!isFiniteNumber(value) || value <= 0) {
+    return 1
+  }
+  return clamp(value, MIN_ZOOM_FACTOR, MAX_ZOOM_FACTOR)
+}
+
+export function normalizeNativeWindowState(value: unknown): NativeWindowState | undefined {
+  if (!value || typeof value !== "object") {
+    return undefined
+  }
+
+  const candidate = value as Partial<NativeWindowState>
+  const bounds = candidate.bounds
+  if (
+    !bounds ||
+    !isFiniteNumber(bounds.x) ||
+    !isFiniteNumber(bounds.y) ||
+    !isFiniteNumber(bounds.width) ||
+    !isFiniteNumber(bounds.height) ||
+    bounds.width <= 0 ||
+    bounds.height <= 0
+  ) {
+    return undefined
+  }
+
+  return {
+    bounds: {
+      x: Math.round(bounds.x),
+      y: Math.round(bounds.y),
+      width: Math.round(bounds.width),
+      height: Math.round(bounds.height),
+    },
+    maximized: candidate.maximized === true,
+    fullscreen: candidate.fullscreen === true,
+    zoomFactor: normalizeZoomFactor(candidate.zoomFactor),
+  }
+}
+
+export function clampWindowBounds(bounds: WindowBounds, displays: DisplayWorkArea[]): WindowBounds | undefined {
+  const normalized = normalizeNativeWindowState({ bounds, maximized: false, fullscreen: false, zoomFactor: 1 })?.bounds
+  const usableDisplays = displays.filter(
+    (area) =>
+      isFiniteNumber(area.x) &&
+      isFiniteNumber(area.y) &&
+      isFiniteNumber(area.width) &&
+      isFiniteNumber(area.height) &&
+      area.width > 0 &&
+      area.height > 0,
+  )
+  if (!normalized || usableDisplays.length === 0) {
+    return undefined
+  }
+
+  const display = usableDisplays.reduce((best, area) => {
+    const bestIntersection = intersectionArea(normalized, best)
+    const areaIntersection = intersectionArea(normalized, area)
+    if (areaIntersection !== bestIntersection) {
+      return areaIntersection > bestIntersection ? area : best
+    }
+    return centerDistanceSquared(normalized, area) < centerDistanceSquared(normalized, best) ? area : best
+  })
+
+  const maximumWidth = Math.max(1, Math.floor(display.width))
+  const maximumHeight = Math.max(1, Math.floor(display.height))
+  const minimumWidth = Math.min(MIN_WINDOW_WIDTH, maximumWidth)
+  const minimumHeight = Math.min(MIN_WINDOW_HEIGHT, maximumHeight)
+  const width = clamp(normalized.width, minimumWidth, maximumWidth)
+  const height = clamp(normalized.height, minimumHeight, maximumHeight)
+  const x = clamp(normalized.x, display.x, display.x + maximumWidth - width)
+  const y = clamp(normalized.y, display.y, display.y + maximumHeight - height)
+
+  return { x, y, width, height }
+}
+
+export function restoreWindowState(window: BrowserWindow, state: NativeWindowState | undefined, bounds: WindowBounds | undefined) {
+  if (!state) {
+    return
+  }
+
+  if (bounds) {
+    window.setPosition(bounds.x, bounds.y)
+    window.setContentSize(bounds.width, bounds.height)
+  }
+  window.webContents.setZoomFactor(normalizeZoomFactor(state.zoomFactor))
+  if (state.maximized) {
+    window.maximize()
+  }
+  if (state.fullscreen) {
+    window.setFullScreen(true)
+  }
+}
+
+export function installWindowZoomInput(window: BrowserWindow, setZoomLevel: (level: number) => void): void {
+  const changeZoom = (delta: number) => setZoomLevel(window.webContents.getZoomLevel() + delta)
+  window.webContents.on("before-input-event", (event, input) => {
+    if (input.type !== "keyDown" || (!input.control && !input.meta) || input.alt) return
+    if (input.key === "+" || input.key === "=") {
+      event.preventDefault()
+      changeZoom(0.5)
+    } else if (input.key === "-") {
+      event.preventDefault()
+      changeZoom(-0.5)
+    } else if (input.key === "0") {
+      event.preventDefault()
+      setZoomLevel(0)
+    }
+  })
+  window.webContents.on("zoom-changed", (event, direction) => {
+    event.preventDefault()
+    changeZoom(direction === "in" ? 0.5 : -0.5)
+  })
+}
+
+export class WindowStateTracker {
+  private saveTimer: ReturnType<typeof setTimeout> | undefined
+  private desiredZoomFactor: number
+  private normalBounds: WindowBounds
+
+  constructor(
+    private readonly window: BrowserWindow,
+    private readonly clientState: ClientStateManager,
+    initialState?: NativeWindowState,
+  ) {
+    this.desiredZoomFactor = normalizeZoomFactor(initialState?.zoomFactor)
+    const [x, y] = typeof window.getPosition === "function" ? window.getPosition() : [0, 0]
+    const [width, height] = typeof window.getContentSize === "function"
+      ? window.getContentSize()
+      : [DEFAULT_WINDOW_WIDTH, DEFAULT_WINDOW_HEIGHT]
+    this.normalBounds = initialState?.bounds ?? { x, y, width, height }
+
+    for (const event of ["move", "resize"]) {
+      window.on(event as "move", () => {
+        if (!window.isMaximized() && !window.isFullScreen()) this.captureNormalBounds()
+        this.scheduleSave()
+      })
+    }
+    for (const event of ["maximize", "unmaximize", "enter-full-screen", "leave-full-screen"]) {
+      window.on(event as "maximize", () => this.scheduleSave())
+    }
+    window.webContents.on("zoom-changed", () => this.scheduleSave())
+    window.webContents.on("did-start-navigation", (_event, _url, _isInPlace, isMainFrame) => {
+      if (isMainFrame && !window.webContents.isDestroyed()) {
+        this.desiredZoomFactor = normalizeZoomFactor(window.webContents.getZoomFactor())
+      }
+    })
+    window.webContents.on("did-finish-load", () => {
+      if (!window.webContents.isDestroyed()) {
+        window.webContents.setZoomFactor(this.desiredZoomFactor)
+      }
+    })
+    window.on("closed", () => this.clearTimer())
+  }
+
+  async flush(): Promise<void> {
+    this.clearTimer()
+    if (!this.window.isDestroyed()) {
+      await this.captureAndQueue()
+    }
+    await this.clientState.flush()
+  }
+
+  setZoomLevel(level: number): void {
+    if (this.window.isDestroyed() || this.window.webContents.isDestroyed()) return
+    this.window.webContents.setZoomLevel(level)
+    this.desiredZoomFactor = normalizeZoomFactor(this.window.webContents.getZoomFactor())
+    this.scheduleSave()
+  }
+
+  private scheduleSave() {
+    this.clearTimer()
+    this.saveTimer = setTimeout(() => {
+      this.saveTimer = undefined
+      void this.saveNow()
+    }, SAVE_DEBOUNCE_MS)
+  }
+
+  private clearTimer() {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer)
+      this.saveTimer = undefined
+    }
+  }
+
+  private async saveNow() {
+    try {
+      await this.captureAndQueue()
+    } catch (error) {
+      console.warn("[client-state] failed to save window state", error)
+    }
+  }
+
+  private captureAndQueue(): Promise<boolean> {
+    if (this.window.isDestroyed() || this.window.webContents.isDestroyed()) {
+      return Promise.resolve(false)
+    }
+
+    this.desiredZoomFactor = normalizeZoomFactor(this.window.webContents.getZoomFactor())
+    if (!this.window.isMaximized() && !this.window.isFullScreen()) this.captureNormalBounds()
+    return this.clientState.saveWindowState({
+      bounds: this.normalBounds,
+      maximized: this.window.isMaximized(),
+      fullscreen: this.window.isFullScreen(),
+      zoomFactor: this.desiredZoomFactor,
+    })
+  }
+
+  private captureNormalBounds(): void {
+    const [x, y] = this.window.getPosition()
+    const [width, height] = this.window.getContentSize()
+    this.normalBounds = { x, y, width, height }
+  }
+}
diff --git a/packages/electron-app/electron/preload/index.cjs b/packages/electron-app/electron/preload/index.cjs
index b39fdea0..0a35f669 100644
--- a/packages/electron-app/electron/preload/index.cjs
+++ b/packages/electron-app/electron/preload/index.cjs
@@ -37,6 +37,12 @@ const localElectronAPI = {
   setWakeLock: (enabled) => ipcRenderer.invoke("power:setWakeLock", Boolean(enabled)),
   showNotification: (payload) => ipcRenderer.invoke("notifications:show", payload),
   openRemoteWindow: (payload) => ipcRenderer.invoke("remote:openWindow", payload),
+  claimClientStateAccess: (token) => ipcRenderer.invoke("client-state:claimAccess", token),
+  loadClientState: (token) => ipcRenderer.invoke("client-state:load", token),
+  saveClientState: (token, snapshot) => ipcRenderer.invoke("client-state:save", token, snapshot),
+  setClientStateRestoreEnabled: (token, enabled) =>
+    ipcRenderer.invoke("client-state:setRestoreEnabled", token, Boolean(enabled)),
+  clearClientState: (token) => ipcRenderer.invoke("client-state:clear", token),
 }
 
 const remoteElectronAPI = {
diff --git a/packages/electron-app/electron/resources/cli-supervisor.cjs b/packages/electron-app/electron/resources/cli-supervisor.cjs
deleted file mode 100644
index 3ac319e3..00000000
--- a/packages/electron-app/electron/resources/cli-supervisor.cjs
+++ /dev/null
@@ -1,131 +0,0 @@
-#!/usr/bin/env node
-
-const { spawn } = require("child_process")
-
-const SHUTDOWN_GRACE_MS = 30_000
-
-let child = null
-let shutdownTimer = null
-
-function log(message, error) {
-  if (error) {
-    console.error(`[cli-supervisor] ${message}`, error)
-    return
-  }
-  console.log(`[cli-supervisor] ${message}`)
-}
-
-function clearShutdownTimer() {
-  if (shutdownTimer) {
-    clearTimeout(shutdownTimer)
-    shutdownTimer = null
-  }
-}
-
-function forwardStream(stream, target) {
-  if (!stream) return
-  stream.on("data", (chunk) => {
-    target.write(chunk)
-  })
-}
-
-function terminateChild(force) {
-  if (!child || child.exitCode !== null || child.signalCode !== null) {
-    return
-  }
-
-  try {
-    child.kill(force ? "SIGKILL" : "SIGTERM")
-  } catch {
-    // no-op
-  }
-}
-
-function requestShutdown(force = false) {
-  if (!child) {
-    process.exit(force ? 1 : 0)
-    return
-  }
-
-  terminateChild(force)
-  if (force) {
-    process.exit(1)
-    return
-  }
-
-  clearShutdownTimer()
-  shutdownTimer = setTimeout(() => {
-    log(`shutdown timed out after ${SHUTDOWN_GRACE_MS}ms; forcing child termination`)
-    terminateChild(true)
-  }, SHUTDOWN_GRACE_MS)
-  shutdownTimer.unref()
-}
-
-function installShutdownHandlers() {
-  process.on("SIGTERM", () => requestShutdown(false))
-  process.on("SIGINT", () => requestShutdown(false))
-  process.on("disconnect", () => requestShutdown(false))
-  process.on("uncaughtException", (error) => {
-    log("uncaught exception", error)
-    requestShutdown(true)
-  })
-  process.on("unhandledRejection", (error) => {
-    log("unhandled rejection", error)
-    requestShutdown(true)
-  })
-}
-
-function parsePayload() {
-  const raw = process.argv[2]
-  if (!raw) {
-    throw new Error("Supervisor payload is required")
-  }
-
-  const parsed = JSON.parse(raw)
-  if (!parsed || typeof parsed !== "object") {
-    throw new Error("Supervisor payload must be an object")
-  }
-  if (typeof parsed.command !== "string" || parsed.command.trim().length === 0) {
-    throw new Error("Supervisor payload command is required")
-  }
-  if (!Array.isArray(parsed.args) || !parsed.args.every((value) => typeof value === "string")) {
-    throw new Error("Supervisor payload args must be a string array")
-  }
-
-  return {
-    command: parsed.command,
-    args: parsed.args,
-    cwd: typeof parsed.cwd === "string" && parsed.cwd.trim().length > 0 ? parsed.cwd : process.cwd(),
-  }
-}
-
-function main() {
-  installShutdownHandlers()
-
-  const payload = parsePayload()
-  log(`launching shell command: ${payload.command} ${payload.args.join(" ")}`)
-
-  child = spawn(payload.command, payload.args, {
-    cwd: payload.cwd,
-    env: process.env,
-    shell: false,
-    stdio: ["ignore", "pipe", "pipe"],
-  })
-
-  forwardStream(child.stdout, process.stdout)
-  forwardStream(child.stderr, process.stderr)
-
-  child.on("error", (error) => {
-    log("failed to spawn shell command", error)
-    process.exit(1)
-  })
-
-  child.on("exit", (code, signal) => {
-    clearShutdownTimer()
-    log(`child exited code=${code ?? ""} signal=${signal ?? ""}`)
-    process.exitCode = typeof code === "number" ? code : signal ? 1 : 0
-    process.exit()
-  })
-}
-
-main()
diff --git a/packages/electron-app/package.json b/packages/electron-app/package.json
index 8bb58526..339f56e8 100644
--- a/packages/electron-app/package.json
+++ b/packages/electron-app/package.json
@@ -24,6 +24,7 @@
     "prebuild": "npm run prepare:resources",
     "build": "electron-vite build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test:native": "node --import tsx --test electron/main/client-state-cross-host.test.ts electron/main/client-state-process.test.ts electron/main/client-state.test.ts electron/main/client-state-ipc.test.ts electron/main/client-state-navigation.test.ts electron/main/client-state-lifecycle.test.ts electron/main/process-stop.test.ts electron/main/renderer-client-state-flush.test.ts electron/main/renderer-origin.test.ts electron/main/serialized-lifecycle.test.ts electron/main/window-state.test.ts",
     "preview": "electron-vite preview",
     "build:binaries": "node scripts/build.js",
     "build:mac": "node scripts/build.js mac",
@@ -131,12 +132,10 @@
       "createStartMenuShortcut": true
     },
     "linux": {
+      "executableName": "CodeNomad",
       "target": [
         {
-          "target": "zip"
-        },
-        {
-          "target": "AppImage"
+          "target": "tar.gz"
         }
       ],
       "artifactName": "CodeNomad-Electron-linux-${arch}-${version}.${ext}",
diff --git a/packages/server/README.md b/packages/server/README.md
index ad24868c..3f19b5a1 100644
--- a/packages/server/README.md
+++ b/packages/server/README.md
@@ -217,3 +217,15 @@ When running as a server CodeNomad can also be installed as a PWA from any suppo
 
 - **Config**: `~/.config/codenomad/config.json`
 - **Instance Data**: `~/.config/codenomad/instances` (chat history, etc.)
+
+### Provider Plan Usage
+
+The Status panel automatically displays quota information for the provider used by the active session. CodeNomad reads existing OpenCode credentials and never returns provider secrets through its API.
+
+Some optional usage integrations require credentials that OpenCode does not expose. They can be enabled without UI configuration through these environment variables:
+
+- Google token refresh: `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET`
+- Antigravity token refresh: `ANTIGRAVITY_OAUTH_CLIENT_ID` and `ANTIGRAVITY_OAUTH_CLIENT_SECRET`
+- Cursor: `CURSOR_ACCESS_TOKEN` or `CURSOR_TOKEN`, with optional `CURSOR_REFRESH_TOKEN`
+- Ollama Cloud: `OLLAMA_CLOUD_COOKIE`
+- OpenCode Go: `OPENCODE_GO_WORKSPACE_ID` and `OPENCODE_GO_AUTH_COOKIE`
diff --git a/packages/server/THIRD_PARTY_NOTICES.md b/packages/server/THIRD_PARTY_NOTICES.md
new file mode 100644
index 00000000..f44c4033
--- /dev/null
+++ b/packages/server/THIRD_PARTY_NOTICES.md
@@ -0,0 +1,26 @@
+# Third-Party Notices
+
+The provider usage adapters are derived from OpenChamber:
+https://github.com/openchamber/openchamber
+
+MIT License
+
+Copyright (c) 2025 Bohdan Triapitsyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/server/package.json b/packages/server/package.json
index 15228764..3ca35925 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -28,6 +28,7 @@
     "@fastify/cors": "^8.5.0",
     "@fastify/reply-from": "^9.8.0",
     "@fastify/static": "^7.0.4",
+    "@opencode-ai/sdk": "^1.17.8",
     "commander": "^12.1.0",
     "fastify": "^4.28.1",
     "fuzzysort": "^2.0.4",
diff --git a/packages/server/src/api-types.ts b/packages/server/src/api-types.ts
index d2349cde..d61b12f0 100644
--- a/packages/server/src/api-types.ts
+++ b/packages/server/src/api-types.ts
@@ -16,6 +16,8 @@ export type WorkspaceStatus = "starting" | "ready" | "stopped" | "error"
 
 export interface WorkspaceDescriptor {
   id: string
+  /** Correlates creation events with the client request that initiated them. */
+  requestId?: string
   /** Absolute path on the server host. */
   path: string
   name?: string
@@ -38,6 +40,9 @@ export interface WorkspaceDescriptor {
 export interface WorkspaceCreateRequest {
   path: string
   name?: string
+  binaryPath?: string
+  requestId?: string
+  forceNew?: boolean
 }
 
 export interface WorkspaceCloneRequest {
@@ -50,7 +55,10 @@ export interface WorkspaceCloneResponse {
   path: string
 }
 
-export type WorkspaceCreateResponse = WorkspaceDescriptor
+export type WorkspaceCreateResponse = WorkspaceDescriptor & {
+  /** True when an active workspace with the same canonical path was returned. */
+  reused?: true
+}
 export type WorkspaceListResponse = WorkspaceDescriptor[]
 export type WorkspaceDetailResponse = WorkspaceDescriptor
 
@@ -59,6 +67,26 @@ export interface WorkspaceDeleteResponse {
   status: WorkspaceStatus
 }
 
+export interface ProviderUsageWindow {
+  usedPercent: number | null
+  remainingPercent: number | null
+  windowSeconds: number | null
+  resetAt: number | null
+  valueLabel?: string
+}
+
+export interface ProviderUsageResponse {
+  requestedProviderId: string
+  providerId: string | null
+  providerName: string
+  modelId?: string
+  supported: boolean
+  configured: boolean
+  ok: boolean
+  windows: Record<string, ProviderUsageWindow>
+  fetchedAt: number
+}
+
 export type WorktreeKind = "root" | "worktree"
 
 export interface WorktreeDescriptor {
@@ -328,6 +356,19 @@ export interface BinaryValidationResult {
   error?: string
 }
 
+export interface OpenCodeUpdateStatus {
+  currentVersion: string
+  latestVersion: string | null
+  updateAvailable: boolean | null
+  canUpgrade: boolean
+  checkError?: "update_check_failed"
+}
+
+export interface OpenCodeUpdateResponse {
+  success: boolean
+  version: string
+}
+
 export interface SpeechSegment {
   startMs: number
   endMs: number
@@ -347,6 +388,11 @@ export interface SpeechCapabilitiesResponse {
   ttsVoice: string
   ttsFormats: string[]
   streamingTtsFormats: string[]
+  separateProviders?: boolean
+  sttConfigured?: boolean
+  ttsConfigured?: boolean
+  sttBaseUrl?: string
+  ttsBaseUrl?: string
 }
 
 export interface SpeechTranscriptionResponse {
@@ -365,6 +411,14 @@ export interface VoiceModeStateResponse {
   enabled: boolean
 }
 
+export interface YoloStateResponse {
+  enabled: boolean
+}
+
+export interface SessionMetadataResponse {
+  metadata: Record<string, unknown>
+}
+
 export interface RemoteServerProfile {
   id: string
   name: string
@@ -414,12 +468,14 @@ export type WorkspaceEventType =
   | "instance.dataChanged"
   | "instance.event"
   | "instance.eventStatus"
+  | "yolo.stateChanged"
+  | "yolo.autoAccepted"
 
 export type WorkspaceEventPayload =
   | { type: "workspace.created"; workspace: WorkspaceDescriptor }
   | { type: "workspace.started"; workspace: WorkspaceDescriptor }
   | { type: "workspace.error"; workspace: WorkspaceDescriptor }
-  | { type: "workspace.stopped"; workspaceId: string }
+  | { type: "workspace.stopped"; workspaceId: string; reason?: "deleted" | "stopped" }
   | { type: "workspace.log"; entry: WorkspaceLogEntry }
   | { type: "sidecar.updated"; sidecar: SideCar }
   | { type: "sidecar.removed"; sidecarId: string }
@@ -428,6 +484,8 @@ export type WorkspaceEventPayload =
   | { type: "instance.dataChanged"; instanceId: string; data: InstanceData }
   | { type: "instance.event"; instanceId: string; event: InstanceStreamEvent }
   | { type: "instance.eventStatus"; instanceId: string; status: InstanceStreamStatus; reason?: string }
+  | { type: "yolo.stateChanged"; instanceId: string; sessionId: string; enabled: boolean }
+  | { type: "yolo.autoAccepted"; instanceId: string; sessionId: string; permissionId: string }
 
 export interface NetworkAddress {
   ip: string
diff --git a/packages/server/src/config/schema.test.ts b/packages/server/src/config/schema.test.ts
new file mode 100644
index 00000000..1e7cf13b
--- /dev/null
+++ b/packages/server/src/config/schema.test.ts
@@ -0,0 +1,15 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { PreferencesSchema } from "./schema"
+
+describe("chat visibility preferences", () => {
+  it("accepts hidden diagnostics and collapsed usage metrics", () => {
+    const preferences = PreferencesSchema.parse({
+      diagnosticsExpansion: "hidden",
+      usageMetricsExpansion: "collapsed",
+    })
+
+    assert.equal(preferences.diagnosticsExpansion, "hidden")
+    assert.equal(preferences.usageMetricsExpansion, "collapsed")
+  })
+})
diff --git a/packages/server/src/config/schema.ts b/packages/server/src/config/schema.ts
index ec65a5d2..c2ca2a0e 100644
--- a/packages/server/src/config/schema.ts
+++ b/packages/server/src/config/schema.ts
@@ -22,8 +22,9 @@ const PreferencesSchema = z
   modelThinkingSelections: z.record(z.string(), z.string()).default({}),
   diffViewMode: z.enum(["split", "unified"]).default("split"),
   toolOutputExpansion: z.enum(["expanded", "collapsed"]).default("expanded"),
-  diagnosticsExpansion: z.enum(["expanded", "collapsed"]).default("expanded"),
+  diagnosticsExpansion: z.enum(["hidden", "expanded", "collapsed"]).default("expanded"),
   showUsageMetrics: z.boolean().default(true),
+  usageMetricsExpansion: z.enum(["expanded", "collapsed"]).default("collapsed"),
   autoCleanupBlankSessions: z.boolean().default(true),
   listeningMode: z.enum(["local", "all"]).default("local"),
   logLevel: z.enum(["DEBUG", "INFO", "WARN", "ERROR"]).default("DEBUG"),
diff --git a/packages/server/src/events/bus.test.ts b/packages/server/src/events/bus.test.ts
new file mode 100644
index 00000000..71757ceb
--- /dev/null
+++ b/packages/server/src/events/bus.test.ts
@@ -0,0 +1,45 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { EventBus } from "./bus"
+import type { WorkspaceEventPayload } from "../api-types"
+
+describe("event bus instance status replay", () => {
+  it("replays the latest instance status to a late subscriber", () => {
+    const bus = new EventBus()
+    bus.publish({ type: "instance.eventStatus", instanceId: "workspace-1", status: "connecting" })
+    bus.publish({ type: "instance.eventStatus", instanceId: "workspace-1", status: "connected" })
+
+    const received: WorkspaceEventPayload[] = []
+    bus.onEvent((event) => received.push(event))
+
+    assert.deepEqual(received, [
+      { type: "instance.eventStatus", instanceId: "workspace-1", status: "connected" },
+    ])
+  })
+
+  it("delivers terminal disconnects live without replaying stopped workspaces", () => {
+    const bus = new EventBus()
+    bus.publish({ type: "instance.eventStatus", instanceId: "workspace-1", status: "connected" })
+    const live: WorkspaceEventPayload[] = []
+    bus.onEvent((event) => live.push(event))
+    live.length = 0
+
+    bus.publish({
+      type: "instance.eventStatus",
+      instanceId: "workspace-1",
+      status: "disconnected",
+      reason: "workspace stopped",
+    })
+
+    assert.deepEqual(live, [{
+      type: "instance.eventStatus",
+      instanceId: "workspace-1",
+      status: "disconnected",
+      reason: "workspace stopped",
+    }])
+    const replayed: WorkspaceEventPayload[] = []
+    bus.onEvent((event) => replayed.push(event))
+    assert.deepEqual(replayed, [])
+  })
+})
diff --git a/packages/server/src/events/bus.ts b/packages/server/src/events/bus.ts
index fd1e3ce6..637aad1d 100644
--- a/packages/server/src/events/bus.ts
+++ b/packages/server/src/events/bus.ts
@@ -3,11 +3,22 @@ import { WorkspaceEventPayload } from "../api-types"
 import { Logger } from "../logger"
 
 export class EventBus extends EventEmitter {
+  private readonly instanceStatuses = new Map<string, Extract<WorkspaceEventPayload, { type: "instance.eventStatus" }>>()
+
   constructor(private readonly logger?: Logger) {
     super()
   }
 
   publish(event: WorkspaceEventPayload): boolean {
+    if (event.type === "instance.eventStatus") {
+      const terminal = event.status === "disconnected"
+        && (event.reason === "workspace stopped" || event.reason === "workspace error")
+      if (terminal) {
+        this.instanceStatuses.delete(event.instanceId)
+      } else {
+        this.instanceStatuses.set(event.instanceId, event)
+      }
+    }
     if (event.type !== "instance.event" && event.type !== "instance.eventStatus") {
       this.logger?.debug({ type: event.type }, "Publishing workspace event")
       if (this.logger?.isLevelEnabled("trace")) {
@@ -31,6 +42,9 @@ export class EventBus extends EventEmitter {
     this.on("instance.dataChanged", handler)
     this.on("instance.event", handler)
     this.on("instance.eventStatus", handler)
+    this.on("yolo.stateChanged", handler)
+    this.on("yolo.autoAccepted", handler)
+    for (const status of this.instanceStatuses.values()) listener(status)
     return () => {
       this.off("workspace.created", handler)
       this.off("workspace.started", handler)
@@ -44,6 +58,8 @@ export class EventBus extends EventEmitter {
       this.off("instance.dataChanged", handler)
       this.off("instance.event", handler)
       this.off("instance.eventStatus", handler)
+      this.off("yolo.stateChanged", handler)
+      this.off("yolo.autoAccepted", handler)
     }
   }
 }
diff --git a/packages/server/src/filesystem/__tests__/search-cache.test.ts b/packages/server/src/filesystem/__tests__/search-cache.test.ts
index 1823c5f8..8000cf48 100644
--- a/packages/server/src/filesystem/__tests__/search-cache.test.ts
+++ b/packages/server/src/filesystem/__tests__/search-cache.test.ts
@@ -17,10 +17,11 @@ describe("workspace search cache", () => {
     const workspacePath = "/tmp/workspace"
     const startTime = 1_000
 
-    refreshWorkspaceCandidates(workspacePath, () => [createEntry("file-a")], startTime)
+    refreshWorkspaceCandidates(workspacePath, "query-a", () => [createEntry("file-a")], startTime)
 
     const beforeExpiry = getWorkspaceCandidates(
       workspacePath,
+      "query-a",
       startTime + WORKSPACE_CANDIDATE_CACHE_TTL_MS - 1,
     )
     assert.ok(beforeExpiry)
@@ -29,6 +30,7 @@ describe("workspace search cache", () => {
 
     const afterExpiry = getWorkspaceCandidates(
       workspacePath,
+      "query-a",
       startTime + WORKSPACE_CANDIDATE_CACHE_TTL_MS + 1,
     )
     assert.equal(afterExpiry, undefined)
@@ -37,16 +39,32 @@ describe("workspace search cache", () => {
   it("replaces cached entries when manually refreshed", () => {
     const workspacePath = "/tmp/workspace"
 
-    refreshWorkspaceCandidates(workspacePath, () => [createEntry("file-a")], 5_000)
-    const initial = getWorkspaceCandidates(workspacePath, 5_001)
+    refreshWorkspaceCandidates(workspacePath, "query-a", () => [createEntry("file-a")], 5_000)
+    const initial = getWorkspaceCandidates(workspacePath, "query-a", 5_001)
     assert.ok(initial)
     assert.equal(initial[0].name, "file-a")
 
-    refreshWorkspaceCandidates(workspacePath, () => [createEntry("file-b")], 6_000)
-    const refreshed = getWorkspaceCandidates(workspacePath, 6_001)
+    refreshWorkspaceCandidates(workspacePath, "query-a", () => [createEntry("file-b")], 6_000)
+    const refreshed = getWorkspaceCandidates(workspacePath, "query-a", 6_001)
     assert.ok(refreshed)
     assert.equal(refreshed[0].name, "file-b")
   })
+
+  it("does not reuse candidates across query scopes", () => {
+    const workspacePath = "/tmp/workspace"
+
+    refreshWorkspaceCandidates(workspacePath, "query-a", () => [createEntry("file-a")], 5_000)
+    assert.equal(getWorkspaceCandidates(workspacePath, "query-a", 5_001)?.[0].name, "file-a")
+    assert.equal(getWorkspaceCandidates(workspacePath, "query-b", 5_001), undefined)
+
+    refreshWorkspaceCandidates(workspacePath, "query-b", () => [createEntry("file-b")], 5_000)
+    assert.equal(getWorkspaceCandidates(workspacePath, "query-a", 5_001), undefined)
+    assert.equal(getWorkspaceCandidates(workspacePath, "query-b", 5_001)?.[0].name, "file-b")
+
+    clearWorkspaceSearchCache(workspacePath)
+    assert.equal(getWorkspaceCandidates(workspacePath, "query-a", 5_001), undefined)
+    assert.equal(getWorkspaceCandidates(workspacePath, "query-b", 5_001), undefined)
+  })
 })
 
 function createEntry(name: string): FileSystemEntry {
diff --git a/packages/server/src/filesystem/__tests__/search.test.ts b/packages/server/src/filesystem/__tests__/search.test.ts
new file mode 100644
index 00000000..63fae4a7
--- /dev/null
+++ b/packages/server/src/filesystem/__tests__/search.test.ts
@@ -0,0 +1,63 @@
+import assert from "node:assert/strict"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { after, test } from "node:test"
+import { searchWorkspaceFiles } from "../search"
+import { getWorkspaceCandidates } from "../search-cache"
+
+const workspace = fs.mkdtempSync(path.join(os.tmpdir(), "codenomad-search-"))
+
+after(() => fs.rmSync(workspace, { recursive: true, force: true }))
+
+test("finds a matching file after more than 8000 non-matching entries", () => {
+  fs.mkdirSync(path.join(workspace, "a"))
+  fs.mkdirSync(path.join(workspace, "b"))
+
+  const [targetDirName, fillerDirName] = fs.readdirSync(workspace)
+  const fillerDir = path.join(workspace, fillerDirName)
+  const targetDir = path.join(workspace, targetDirName)
+
+  for (let index = 0; index < 8_001; index += 1) {
+    fs.writeFileSync(path.join(fillerDir, `filler-${index}.txt`), "")
+  }
+  fs.writeFileSync(path.join(targetDir, "unique-search-target.txt"), "")
+
+  const results = searchWorkspaceFiles(workspace, "unique-search-target", {
+    type: "file",
+    refresh: true,
+  })
+
+  assert.equal(results.some((entry) => entry.name === "unique-search-target.txt"), true)
+
+  searchWorkspaceFiles(workspace, "filler", { type: "file", refresh: true })
+  assert.equal(getWorkspaceCandidates(workspace, "file\0filler")?.length, 8_000)
+})
+
+test("does not revisit directory links", () => {
+  const cyclicWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "codenomad-search-cycle-"))
+  try {
+    fs.symlinkSync(cyclicWorkspace, path.join(cyclicWorkspace, "cycle"), process.platform === "win32" ? "junction" : "dir")
+    assert.deepEqual(searchWorkspaceFiles(cyclicWorkspace, "not-present", { refresh: true }), [])
+  } finally {
+    fs.rmSync(cyclicWorkspace, { recursive: true, force: true })
+  }
+})
+
+test("indexes both real and linked directory paths", () => {
+  const linkedWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "codenomad-search-link-"))
+  try {
+    const realDirectory = path.join(linkedWorkspace, "b")
+    fs.mkdirSync(realDirectory)
+    fs.writeFileSync(path.join(realDirectory, "needle.txt"), "")
+    fs.symlinkSync(realDirectory, path.join(linkedWorkspace, "a"), process.platform === "win32" ? "junction" : "dir")
+
+    const linkedResults = searchWorkspaceFiles(linkedWorkspace, "a/needle", { type: "file", refresh: true })
+    const realResults = searchWorkspaceFiles(linkedWorkspace, "b/needle", { type: "file", refresh: true })
+
+    assert.equal(linkedResults.some((entry) => entry.path === "a/needle.txt"), true)
+    assert.equal(realResults.some((entry) => entry.path === "b/needle.txt"), true)
+  } finally {
+    fs.rmSync(linkedWorkspace, { recursive: true, force: true })
+  }
+})
diff --git a/packages/server/src/filesystem/search-cache.ts b/packages/server/src/filesystem/search-cache.ts
index 5568204b..17cf4e16 100644
--- a/packages/server/src/filesystem/search-cache.ts
+++ b/packages/server/src/filesystem/search-cache.ts
@@ -4,16 +4,17 @@ import type { FileSystemEntry } from "../api-types"
 export const WORKSPACE_CANDIDATE_CACHE_TTL_MS = 30_000
 
 interface WorkspaceCandidateCacheEntry {
+  scope: string
   expiresAt: number
   candidates: FileSystemEntry[]
 }
 
 const workspaceCandidateCache = new Map<string, WorkspaceCandidateCacheEntry>()
 
-export function getWorkspaceCandidates(rootDir: string, now = Date.now()): FileSystemEntry[] | undefined {
+export function getWorkspaceCandidates(rootDir: string, scope: string, now = Date.now()): FileSystemEntry[] | undefined {
   const key = normalizeKey(rootDir)
   const cached = workspaceCandidateCache.get(key)
-  if (!cached) {
+  if (!cached || cached.scope !== scope) {
     return undefined
   }
 
@@ -27,19 +28,16 @@ export function getWorkspaceCandidates(rootDir: string, now = Date.now()): FileS
 
 export function refreshWorkspaceCandidates(
   rootDir: string,
+  scope: string,
   builder: () => FileSystemEntry[],
   now = Date.now(),
 ): FileSystemEntry[] {
   const key = normalizeKey(rootDir)
   const freshCandidates = builder()
 
-  if (!freshCandidates || freshCandidates.length === 0) {
-    workspaceCandidateCache.delete(key)
-    return []
-  }
-
   const storedCandidates = cloneEntries(freshCandidates)
   workspaceCandidateCache.set(key, {
+    scope,
     expiresAt: now + WORKSPACE_CANDIDATE_CACHE_TTL_MS,
     candidates: storedCandidates,
   })
@@ -53,8 +51,7 @@ export function clearWorkspaceSearchCache(rootDir?: string) {
     return
   }
 
-  const key = normalizeKey(rootDir)
-  workspaceCandidateCache.delete(key)
+  workspaceCandidateCache.delete(normalizeKey(rootDir))
 }
 
 function cloneEntries(entries: FileSystemEntry[]): FileSystemEntry[] {
diff --git a/packages/server/src/filesystem/search.ts b/packages/server/src/filesystem/search.ts
index 77347b05..53da6066 100644
--- a/packages/server/src/filesystem/search.ts
+++ b/packages/server/src/filesystem/search.ts
@@ -40,16 +40,19 @@ export function searchWorkspaceFiles(
   const limit = normalizeLimit(options.limit)
   const typeFilter: WorkspaceFileSearchType = options.type ?? "all"
   const refreshRequested = options.refresh === true
+  const cacheScope = `${typeFilter}\0${trimmedQuery.toLowerCase()}`
 
   let entries: FileSystemEntry[] | undefined
 
   try {
     if (!refreshRequested) {
-      entries = getWorkspaceCandidates(normalizedRoot)
+      entries = getWorkspaceCandidates(normalizedRoot, cacheScope)
     }
 
     if (!entries) {
-      entries = refreshWorkspaceCandidates(normalizedRoot, () => collectCandidates(normalizedRoot))
+      entries = refreshWorkspaceCandidates(normalizedRoot, cacheScope, () =>
+        collectCandidates(normalizedRoot, trimmedQuery, typeFilter),
+      )
     }
   } catch (error) {
     clearWorkspaceSearchCache(normalizedRoot)
@@ -57,7 +60,6 @@ export function searchWorkspaceFiles(
   }
 
   if (!entries || entries.length === 0) {
-    clearWorkspaceSearchCache(normalizedRoot)
     return []
   }
 
@@ -80,16 +82,25 @@ export function searchWorkspaceFiles(
 }
 
 
-function collectCandidates(rootDir: string): FileSystemEntry[] {
-  const queue: string[] = [""]
+function collectCandidates(rootDir: string, query: string, filter: WorkspaceFileSearchType): FileSystemEntry[] {
+  const queue: Array<{ relativeDir: string; ancestors: ReadonlySet<string> }> = [
+    { relativeDir: "", ancestors: new Set() },
+  ]
   const entries: FileSystemEntry[] = []
 
   while (queue.length > 0 && entries.length < MAX_CANDIDATES) {
-    const relativeDir = queue.pop() || ""
+    const queuedDirectory = queue.pop()!
+    const { relativeDir, ancestors } = queuedDirectory
     const absoluteDir = relativeDir ? path.join(rootDir, relativeDir) : rootDir
 
     let dirents: fs.Dirent[]
+    let branchAncestors: ReadonlySet<string>
     try {
+      const realDir = normalizeDirectoryIdentity(fs.realpathSync.native(absoluteDir))
+      if (ancestors.has(realDir)) {
+        continue
+      }
+      branchAncestors = new Set([...ancestors, realDir])
       dirents = fs.readdirSync(absoluteDir, { withFileTypes: true })
     } catch {
       continue
@@ -115,9 +126,7 @@ function collectCandidates(rootDir: string): FileSystemEntry[] {
       const isDirectory = stats.isDirectory()
 
       if (isDirectory && !IGNORED_DIRECTORIES.has(lowerName)) {
-        if (entries.length < MAX_CANDIDATES) {
-          queue.push(relativePath)
-        }
+        queue.push({ relativeDir: relativePath, ancestors: branchAncestors })
       }
 
       const entryType: FileSystemEntry["type"] = isDirectory ? "directory" : "file"
@@ -131,8 +140,11 @@ function collectCandidates(rootDir: string): FileSystemEntry[] {
         modifiedAt: stats.mtime.toISOString(),
       }
 
-      entries.push(entry)
+      if (!shouldInclude(entry.type, filter) || !fuzzysort.single(query, buildSearchKey(entry))) {
+        continue
+      }
 
+      entries.push(entry)
       if (entries.length >= MAX_CANDIDATES) {
         break
       }
@@ -182,3 +194,7 @@ function normalizeRelativeEntryPath(relativePath: string): string {
 function buildSearchKey(entry: FileSystemEntry) {
   return entry.path.toLowerCase()
 }
+
+function normalizeDirectoryIdentity(directoryPath: string) {
+  return process.platform === "win32" ? directoryPath.toLowerCase() : directoryPath
+}
diff --git a/packages/server/src/index.test.ts b/packages/server/src/index.test.ts
new file mode 100644
index 00000000..2e8f4cf8
--- /dev/null
+++ b/packages/server/src/index.test.ts
@@ -0,0 +1,73 @@
+import assert from "node:assert/strict"
+import { spawn } from "node:child_process"
+import { once } from "node:events"
+import { describe, it } from "node:test"
+
+import { installShutdownSignalHandlers, installShutdownStdinHandler, STDIN_SHUTDOWN_COMMAND } from "./index"
+import { createServerShutdownHandler } from "./shutdown"
+
+describe("CLI shutdown signal registration", () => {
+  it("routes a second process signal to forced nonzero escalation", async () => {
+    const listeners = new Map<string, () => void>()
+    let finishCleanup!: () => void
+    const cleanup = new Promise<void>((resolve) => {
+      finishCleanup = resolve
+    })
+    const exits: number[] = []
+    let handled: Promise<void> | undefined
+    const shutdown = createServerShutdownHandler({
+      shutdown: () => cleanup,
+      logger: { info() {}, warn() {}, error() {} },
+      forceExit: (code) => exits.push(code),
+      setExitCode: () => undefined,
+      reportStatus: () => undefined,
+    })
+    installShutdownSignalHandlers(
+      { on: (signal, listener) => listeners.set(signal, listener) },
+      (signal) => (handled = shutdown(signal)),
+    )
+
+    listeners.get("SIGINT")?.()
+    listeners.get("SIGTERM")?.()
+    assert.deepEqual(exits, [1])
+
+    finishCleanup()
+    await handled
+  })
+
+  it("coalesces chunked and repeated stdin shutdown commands through the same handler", async () => {
+    const listeners = new Map<string, (chunk: Buffer | string) => void>()
+    const triggers: string[] = []
+    let destroys = 0
+    const source = {
+      on: (event: "data", listener: (chunk: Buffer | string) => void) => listeners.set(event, listener),
+      off: (event: "data", listener: (chunk: Buffer | string) => void) => {
+        if (listeners.get(event) === listener) listeners.delete(event)
+      },
+      destroy: () => { destroys++ },
+    }
+    installShutdownStdinHandler(source, async (trigger) => { triggers.push(trigger) })
+
+    const listener = listeners.get("data")!
+    listener(STDIN_SHUTDOWN_COMMAND.slice(0, 8))
+    listener(`${STDIN_SHUTDOWN_COMMAND.slice(8)}\n${STDIN_SHUTDOWN_COMMAND}\n`)
+    listener(`${STDIN_SHUTDOWN_COMMAND}\n`)
+    await Promise.resolve()
+
+    assert.deepEqual(triggers, ["stdin"])
+    assert.equal(destroys, 1)
+    assert.equal(listeners.has("data"), false)
+  })
+
+  it("allows a real piped process to exit naturally after the shutdown command", { timeout: 5_000 }, async () => {
+    const moduleUrl = new URL("./index.ts", import.meta.url).href
+    const child = spawn(process.execPath, ["--import", "tsx", "--input-type=module", "-e", `
+      import { installShutdownStdinHandler } from ${JSON.stringify(moduleUrl)}
+      installShutdownStdinHandler(process.stdin, async () => { process.exitCode = 0 })
+    `], { stdio: ["pipe", "ignore", "inherit"] })
+
+    child.stdin.end(`${STDIN_SHUTDOWN_COMMAND}\n`)
+    const [code] = await once(child, "exit")
+    assert.equal(code, 0)
+  })
+})
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index 935cc040..0f06a2cf 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -32,6 +32,10 @@ import { ClientConnectionManager } from "./clients/connection-manager"
 import { PluginChannelManager } from "./plugins/channel"
 import { VoiceModeManager } from "./plugins/voice-mode"
 import { runCliUpgrade } from "./cli-upgrade"
+import { createServerShutdownHandler, orchestrateServerShutdown, type ServerShutdownTrigger } from "./shutdown"
+import { AutoAcceptManager } from "./permissions/auto-accept-manager"
+import { createOpencodePermissionReplier } from "./permissions/opencode-replier"
+import { createOpencodeYoloPersistence } from "./permissions/opencode-yolo-metadata"
 
 const require = createRequire(import.meta.url)
 
@@ -73,6 +77,46 @@ const DEFAULT_HOST = "127.0.0.1"
 const DEFAULT_CONFIG_PATH = "~/.config/codenomad/config.json"
 const DEFAULT_HTTPS_PORT = 9898
 const DEFAULT_HTTP_PORT = 9899
+export const STDIN_SHUTDOWN_COMMAND = "codenomad:shutdown"
+
+interface ShutdownSignalSource {
+  on: (signal: "SIGINT" | "SIGTERM", listener: () => void) => unknown
+}
+
+export function installShutdownSignalHandlers(
+  source: ShutdownSignalSource,
+  shutdown: (signal: ServerShutdownTrigger) => Promise<void>,
+): void {
+  source.on("SIGINT", () => void shutdown("SIGINT"))
+  source.on("SIGTERM", () => void shutdown("SIGTERM"))
+}
+
+interface ShutdownStdinSource {
+  on(event: "data", listener: (chunk: Buffer | string) => void): unknown
+  off?(event: "data", listener: (chunk: Buffer | string) => void): unknown
+  destroy?(): unknown
+}
+
+export function installShutdownStdinHandler(
+  source: ShutdownStdinSource,
+  shutdown: (signal: ServerShutdownTrigger) => Promise<void>,
+): void {
+  let buffer = ""
+  let requested = false
+  const onData = (chunk: Buffer | string) => {
+    if (requested) return
+    buffer += chunk.toString()
+    const lines = buffer.split(/\r?\n/)
+    buffer = lines.pop() ?? ""
+    if (!lines.some((line) => line.trim() === STDIN_SHUTDOWN_COMMAND)) return
+
+    requested = true
+    source.off?.("data", onData)
+    source.destroy?.()
+    void shutdown("stdin")
+  }
+  source.on("data", onData)
+}
 
 function parseCliOptions(argv: string[]): CliOptions {
   const program = new Command()
@@ -343,6 +387,15 @@ async function main() {
     logger: logger.child({ component: "sidecars" }),
   })
   const previewManager = new PreviewManager()
+  const yoloLogger = logger.child({ component: "yolo" })
+  const sessionMetadataPersistence = createOpencodeYoloPersistence(workspaceManager)
+  const yoloManager = new AutoAcceptManager({
+    eventBus,
+    logger: yoloLogger,
+    replier: createOpencodePermissionReplier({ workspaceManager, logger: yoloLogger }),
+    persistence: sessionMetadataPersistence,
+  })
+  yoloManager.start()
   const instanceEventBridge = new InstanceEventBridge({
     workspaceManager,
     eventBus,
@@ -444,6 +497,8 @@ async function main() {
         pluginChannel,
         voiceModeManager,
         remoteProxySessionManager,
+        yoloManager,
+        sessionMetadataPersistence,
         uiStaticDir: uiResolution.uiStaticDir ?? DEFAULT_UI_STATIC_DIR,
         uiDevServerUrl: uiResolution.uiDevServerUrl,
         logger,
@@ -471,6 +526,8 @@ async function main() {
         pluginChannel,
         voiceModeManager,
         remoteProxySessionManager,
+        yoloManager,
+        sessionMetadataPersistence,
         uiStaticDir: uiResolution.uiStaticDir ?? DEFAULT_UI_STATIC_DIR,
         uiDevServerUrl: undefined,
         logger,
@@ -555,68 +612,46 @@ async function main() {
     await launchInBrowser(serverMeta.localUrl, logger.child({ component: "launcher" }))
   }
 
-  let shuttingDown = false
+  const shutdown = createServerShutdownHandler({
+    logger,
+    holdAfterFailure: () => new Promise<void>(() => { setInterval(() => undefined, 60_000) }),
+    setExitCode: (code) => {
+      process.stdin.destroy()
+      process.exitCode = code
+    },
+    shutdown: () =>
+      orchestrateServerShutdown(
+        {
+          stopInstanceEventBridge: () => instanceEventBridge.shutdown(),
+          stopSidecars: () => sidecarManager.shutdown(),
+          stopClientConnections: () => clientConnectionManager.shutdown(),
+          stopRemoteProxySessions: () => remoteProxySessionManager.shutdown(),
+          stopWorkspaces: () => workspaceManager.shutdown(),
+          stopHttpServers: async () => {
+            yoloManager.stop()
+            const results = await Promise.allSettled(servers.map((srv) => srv.stop()))
+            const failures = results.flatMap((result) => (result.status === "rejected" ? [result.reason] : []))
+            if (failures.length > 0) {
+              const error = new Error("One or more HTTP servers failed to stop") as Error & { failures: unknown[] }
+              error.failures = failures
+              throw error
+            }
+            logger.info("HTTP server(s) stopped")
+          },
+          stopReleaseMonitor: () => devReleaseMonitor?.stop(),
+        },
+        logger,
+      ),
+  })
 
-  const shutdown = async () => {
-    if (shuttingDown) {
-      logger.info("Shutdown already in progress, ignoring signal")
-      return
-    }
-    shuttingDown = true
-    logger.info("Received shutdown signal, stopping workspaces and server")
-
-    const shutdownWorkspaces = (async () => {
-      try {
-        instanceEventBridge.shutdown()
-      } catch (error) {
-        logger.warn({ err: error }, "Instance event bridge shutdown failed")
-      }
-
-      try {
-        await sidecarManager.shutdown()
-      } catch (error) {
-        logger.error({ err: error }, "SideCar manager shutdown failed")
-      }
-
-      try {
-        clientConnectionManager.shutdown()
-      } catch (error) {
-        logger.warn({ err: error }, "Client connection manager shutdown failed")
-      }
-
-      try {
-        await workspaceManager.shutdown()
-        logger.info("Workspace manager shutdown complete")
-      } catch (error) {
-        logger.error({ err: error }, "Workspace manager shutdown failed")
-      }
-    })()
-
-    const shutdownHttp = (async () => {
-      try {
-        await Promise.allSettled(servers.map((srv) => srv.stop()))
-        logger.info("HTTP server(s) stopped")
-      } catch (error) {
-        logger.error({ err: error }, "Failed to stop HTTP server")
-      }
-    })()
-
-    await Promise.allSettled([shutdownWorkspaces, shutdownHttp])
-
-    // no-op: remote UI manifest replaces GitHub release monitor
-
-    devReleaseMonitor?.stop()
-
-    logger.info("Exiting process")
-    process.exit(0)
-  }
-
-  process.on("SIGINT", shutdown)
-  process.on("SIGTERM", shutdown)
+  installShutdownSignalHandlers(process, shutdown)
+  installShutdownStdinHandler(process.stdin, shutdown)
 }
 
-main().catch((error) => {
-  const logger = createLogger({ component: "app" })
-  logger.error({ err: error }, "CLI server crashed")
-  process.exit(1)
-})
+if (path.resolve(process.argv[1] ?? "") === __filename) {
+  main().catch((error) => {
+    const logger = createLogger({ component: "app" })
+    logger.error({ err: error }, "CLI server crashed")
+    process.exit(1)
+  })
+}
diff --git a/packages/server/src/opencode-update/service.test.ts b/packages/server/src/opencode-update/service.test.ts
new file mode 100644
index 00000000..2b631529
--- /dev/null
+++ b/packages/server/src/opencode-update/service.test.ts
@@ -0,0 +1,129 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import { OpenCodeUpdateError, OpenCodeUpdateService, type OpenCodeUpdateServiceDeps } from "./service"
+
+function createDeps(overrides: Partial<OpenCodeUpdateServiceDeps> = {}): OpenCodeUpdateServiceDeps {
+  let currentVersion = "1.0.0"
+  return {
+    resolveBinary: () => ({ path: "opencode", label: "OpenCode" }),
+    probeBinary: () => ({ valid: true, version: currentVersion }),
+    findReadyInstanceId: () => "workspace-1",
+    fetchLatestVersion: async () => "1.1.0",
+    upgradeInstance: async (_instanceId, target) => {
+      currentVersion = target
+      return { success: true, version: target }
+    },
+    ...overrides,
+  }
+}
+
+test("reports an available update and caches the latest version", async () => {
+  let checks = 0
+  const service = new OpenCodeUpdateService(createDeps({
+    fetchLatestVersion: async () => {
+      checks += 1
+      return "1.1.0"
+    },
+  }))
+
+  assert.deepEqual(await service.getStatus(), {
+    currentVersion: "1.0.0",
+    latestVersion: "1.1.0",
+    updateAvailable: true,
+    canUpgrade: true,
+  })
+  await service.getStatus()
+  assert.equal(checks, 1)
+})
+
+test("keeps the update visible when no matching instance is ready", async () => {
+  const service = new OpenCodeUpdateService(createDeps({ findReadyInstanceId: () => undefined }))
+
+  assert.deepEqual(await service.getStatus(), {
+    currentVersion: "1.0.0",
+    latestVersion: "1.1.0",
+    updateAvailable: true,
+    canUpgrade: false,
+  })
+})
+
+test("preserves the installed version when the registry check fails", async () => {
+  const service = new OpenCodeUpdateService(createDeps({
+    fetchLatestVersion: async () => {
+      throw new Error("registry unavailable")
+    },
+  }))
+
+  assert.deepEqual(await service.getStatus(), {
+    currentVersion: "1.0.0",
+    latestVersion: null,
+    updateAvailable: null,
+    canUpgrade: false,
+    checkError: "update_check_failed",
+  })
+})
+
+test("upgrades through the matching OpenCode instance to the advertised version", async () => {
+  const calls: Array<{ instanceId: string; target: string }> = []
+  let currentVersion = "1.0.0"
+  const service = new OpenCodeUpdateService(createDeps({
+    probeBinary: () => ({ valid: true, version: currentVersion }),
+    upgradeInstance: async (instanceId, target) => {
+      calls.push({ instanceId, target })
+      currentVersion = target
+      return { success: true, version: target }
+    },
+  }))
+
+  assert.deepEqual(await service.upgrade(), { success: true, version: "1.1.0" })
+  assert.deepEqual(calls, [{ instanceId: "workspace-1", target: "1.1.0" }])
+})
+
+test("rejects success when the configured binary was not updated", async () => {
+  const service = new OpenCodeUpdateService(createDeps({
+    probeBinary: () => ({ valid: true, version: "1.0.0" }),
+    upgradeInstance: async (_instanceId, target) => ({ success: true, version: target }),
+  }))
+
+  await assert.rejects(
+    () => service.upgrade(),
+    (error: unknown) => error instanceof OpenCodeUpdateError && error.code === "upgrade_verification_failed",
+  )
+})
+
+test("joins concurrent upgrades for the same binary", async () => {
+  let currentVersion = "1.0.0"
+  let upgrades = 0
+  let finishUpgrade: (() => void) | undefined
+  const gate = new Promise<void>((resolve) => {
+    finishUpgrade = resolve
+  })
+  const service = new OpenCodeUpdateService(createDeps({
+    probeBinary: () => ({ valid: true, version: currentVersion }),
+    upgradeInstance: async (_instanceId, target) => {
+      upgrades += 1
+      await gate
+      currentVersion = target
+      return { success: true, version: target }
+    },
+  }))
+
+  const first = service.upgrade()
+  const second = service.upgrade()
+  finishUpgrade?.()
+
+  assert.deepEqual(await Promise.all([first, second]), [
+    { success: true, version: "1.1.0" },
+    { success: true, version: "1.1.0" },
+  ])
+  assert.equal(upgrades, 1)
+})
+
+test("rejects an upgrade when no matching OpenCode instance is running", async () => {
+  const service = new OpenCodeUpdateService(createDeps({ findReadyInstanceId: () => undefined }))
+
+  await assert.rejects(
+    () => service.upgrade(),
+    (error: unknown) => error instanceof OpenCodeUpdateError && error.code === "no_ready_instance",
+  )
+})
diff --git a/packages/server/src/opencode-update/service.ts b/packages/server/src/opencode-update/service.ts
new file mode 100644
index 00000000..c84167d2
--- /dev/null
+++ b/packages/server/src/opencode-update/service.ts
@@ -0,0 +1,194 @@
+import { fetch } from "undici"
+import type { OpenCodeUpdateResponse, OpenCodeUpdateStatus } from "../api-types"
+import type { SettingsService } from "../settings/service"
+import { BinaryResolver, type ResolvedBinary } from "../settings/binaries"
+import type { WorkspaceManager } from "../workspaces/manager"
+import { createInstanceClient } from "../workspaces/instance-client"
+import { probeBinaryVersion } from "../workspaces/spawn"
+import { compareVersionStrings, stripTagPrefix } from "../releases/release-monitor"
+
+const OPENCODE_LATEST_URL = "https://registry.npmjs.org/opencode-ai/latest"
+const LATEST_VERSION_CACHE_MS = 5 * 60_000
+const UPGRADE_TIMEOUT_MS = 10 * 60_000
+const inFlightUpgrades = new Map<string, Promise<OpenCodeUpdateResponse>>()
+
+type UpgradeResult = { success: true; version: string } | { success: false; error: string }
+
+export interface OpenCodeUpdateServiceDeps {
+  resolveBinary: () => ResolvedBinary
+  probeBinary: typeof probeBinaryVersion
+  findReadyInstanceId: (binaryPath: string) => string | undefined
+  upgradeInstance: (instanceId: string, target: string) => Promise<UpgradeResult>
+  fetchLatestVersion: () => Promise<string>
+  now?: () => number
+}
+
+export class OpenCodeUpdateError extends Error {
+  constructor(
+    readonly code:
+      | "binary_unavailable"
+      | "no_ready_instance"
+      | "update_check_failed"
+      | "upgrade_failed"
+      | "upgrade_verification_failed",
+    message: string,
+  ) {
+    super(message)
+    this.name = "OpenCodeUpdateError"
+  }
+}
+
+export class OpenCodeUpdateService {
+  private latestVersionCache: { version: string; expiresAt: number } | null = null
+
+  constructor(private readonly deps: OpenCodeUpdateServiceDeps) {}
+
+  async getStatus(): Promise<OpenCodeUpdateStatus> {
+    const binary = this.deps.resolveBinary()
+    const currentVersion = this.readCurrentVersion(binary.path)
+    let latestVersion: string
+    try {
+      latestVersion = await this.readLatestVersion()
+    } catch (error) {
+      if (!(error instanceof OpenCodeUpdateError) || error.code !== "update_check_failed") throw error
+      return {
+        currentVersion,
+        latestVersion: null,
+        updateAvailable: null,
+        canUpgrade: false,
+        checkError: "update_check_failed",
+      }
+    }
+    const updateAvailable = compareVersionStrings(latestVersion, currentVersion) > 0
+    const readyInstanceId = this.deps.findReadyInstanceId(binary.path)
+
+    return {
+      currentVersion,
+      latestVersion,
+      updateAvailable,
+      canUpgrade: updateAvailable && Boolean(readyInstanceId),
+    }
+  }
+
+  upgrade(): Promise<OpenCodeUpdateResponse> {
+    const binary = this.deps.resolveBinary()
+    const existing = inFlightUpgrades.get(binary.path)
+    if (existing) return existing
+
+    const pending = this.performUpgrade(binary).finally(() => {
+      if (inFlightUpgrades.get(binary.path) === pending) inFlightUpgrades.delete(binary.path)
+    })
+    inFlightUpgrades.set(binary.path, pending)
+    return pending
+  }
+
+  private async performUpgrade(binary: ResolvedBinary): Promise<OpenCodeUpdateResponse> {
+    const currentVersion = this.readCurrentVersion(binary.path)
+    const latestVersion = await this.readLatestVersion()
+
+    if (compareVersionStrings(latestVersion, currentVersion) <= 0) {
+      return { success: true, version: currentVersion }
+    }
+
+    const instanceId = this.deps.findReadyInstanceId(binary.path)
+    if (!instanceId) {
+      throw new OpenCodeUpdateError(
+        "no_ready_instance",
+        "No running OpenCode instance uses the configured binary",
+      )
+    }
+
+    try {
+      const result = await this.deps.upgradeInstance(instanceId, latestVersion)
+      if (!result.success) {
+        throw new OpenCodeUpdateError("upgrade_failed", result.error)
+      }
+      const installedVersion = this.readCurrentVersion(binary.path)
+      if (compareVersionStrings(installedVersion, latestVersion) !== 0) {
+        throw new OpenCodeUpdateError(
+          "upgrade_verification_failed",
+          `OpenCode reported ${result.version}, but the configured binary is still ${installedVersion}`,
+        )
+      }
+      return { success: true, version: installedVersion }
+    } catch (error) {
+      if (error instanceof OpenCodeUpdateError) throw error
+      throw new OpenCodeUpdateError(
+        "upgrade_failed",
+        error instanceof Error ? error.message : "OpenCode upgrade failed",
+      )
+    }
+  }
+
+  private readCurrentVersion(binaryPath: string): string {
+    if (process.platform === "win32" && /["\r\n]/.test(binaryPath)) {
+      throw new OpenCodeUpdateError("binary_unavailable", "The configured OpenCode binary path is invalid")
+    }
+    const result = this.deps.probeBinary(binaryPath)
+    const version = stripTagPrefix(result.version)
+    if (!result.valid || !version) {
+      throw new OpenCodeUpdateError("binary_unavailable", result.error ?? "Unable to read OpenCode version")
+    }
+    return version
+  }
+
+  private async readLatestVersion(): Promise<string> {
+    const now = (this.deps.now ?? Date.now)()
+    if (this.latestVersionCache && this.latestVersionCache.expiresAt > now) {
+      return this.latestVersionCache.version
+    }
+
+    try {
+      const version = stripTagPrefix(await this.deps.fetchLatestVersion())
+      if (!version || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw new Error("OpenCode registry returned an invalid version")
+      }
+      this.latestVersionCache = { version, expiresAt: now + LATEST_VERSION_CACHE_MS }
+      return version
+    } catch (error) {
+      throw new OpenCodeUpdateError(
+        "update_check_failed",
+        error instanceof Error ? error.message : "Unable to check the latest OpenCode version",
+      )
+    }
+  }
+}
+
+export async function fetchLatestOpenCodeVersion(): Promise<string> {
+  const response = await fetch(OPENCODE_LATEST_URL, {
+    headers: { Accept: "application/json", "User-Agent": "CodeNomad-CLI" },
+    signal: AbortSignal.timeout(10_000),
+  })
+  if (!response.ok) {
+    throw new Error(`OpenCode registry responded with ${response.status}`)
+  }
+  const payload = (await response.json()) as { version?: unknown }
+  if (typeof payload.version !== "string") {
+    throw new Error("OpenCode registry response did not include a version")
+  }
+  return payload.version
+}
+
+export function createOpenCodeUpdateService(
+  settings: SettingsService,
+  workspaceManager: WorkspaceManager,
+): OpenCodeUpdateService {
+  const binaryResolver = new BinaryResolver(settings)
+  return new OpenCodeUpdateService({
+    resolveBinary: () => {
+      const binary = binaryResolver.resolveDefault()
+      return { ...binary, path: workspaceManager.resolveBinaryPath(binary.path) }
+    },
+    probeBinary: probeBinaryVersion,
+    findReadyInstanceId: (binaryPath) => workspaceManager.findReadyInstanceIdByBinary(binaryPath),
+    fetchLatestVersion: fetchLatestOpenCodeVersion,
+    upgradeInstance: async (instanceId, target) => {
+      const client = createInstanceClient(workspaceManager, instanceId, { timeoutMs: UPGRADE_TIMEOUT_MS })
+      if (!client) {
+        throw new OpenCodeUpdateError("no_ready_instance", "OpenCode instance is not ready")
+      }
+      const { data } = await client.global.upgrade({ target }, { throwOnError: true })
+      return data
+    },
+  })
+}
diff --git a/packages/server/src/permissions/auto-accept-manager.test.ts b/packages/server/src/permissions/auto-accept-manager.test.ts
new file mode 100644
index 00000000..d803587b
--- /dev/null
+++ b/packages/server/src/permissions/auto-accept-manager.test.ts
@@ -0,0 +1,881 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { EventBus } from "../events/bus"
+import { AutoAcceptManager, type AutoAcceptPersistence, type PermissionReplier, type AutoAcceptReply } from "./auto-accept-manager"
+import type { InstanceStreamEvent } from "../api-types"
+import type { Logger } from "../logger"
+
+const noopLogger: Logger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+  trace() {},
+  isLevelEnabled() {
+    return false
+  },
+  child() {
+    return noopLogger
+  },
+} as unknown as Logger
+
+function publishInstanceEvent(bus: EventBus, instanceId: string, event: Record<string, unknown>) {
+  bus.publish({ type: "instance.event", instanceId, event: { ...event } as InstanceStreamEvent })
+}
+
+/** Publish a `session.*` event using the real OpenCode shape (`properties.info`). */
+function publishSession(
+  bus: EventBus,
+  instanceId: string,
+  eventType: "session.updated" | "session.created" | "session.deleted",
+  info: Record<string, unknown>,
+) {
+  publishInstanceEvent(bus, instanceId, { type: eventType, properties: { info: { ...info } } })
+}
+
+describe("AutoAcceptManager session tree", () => {
+  it("ingests session.updated to build the parent chain", () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "master", parentID: null })
+    publishSession(bus, "inst", "session.updated", { id: "child", parentID: "master" })
+
+    assert.equal(manager.isEnabled("inst", "master"), false)
+    manager.toggle("inst", "child")
+    assert.equal(manager.isEnabled("inst", "child"), true)
+    assert.equal(manager.isEnabled("inst", "master"), true)
+
+    manager.stop()
+  })
+
+  it("treats a session with revert as a fork root", () => {
+    const bus = new EventBus(noopLogger)
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier() })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "master", parentID: null })
+    publishSession(bus, "inst", "session.updated", {
+      id: "fork",
+      parentID: "master",
+      revert: { messageID: "m", partID: "p" },
+    })
+
+    manager.toggle("inst", "fork")
+    assert.equal(manager.isEnabled("inst", "fork"), true)
+    assert.equal(manager.isEnabled("inst", "master"), false)
+
+    manager.stop()
+  })
+
+  it("session.deleted removes the tree entry but keeps the toggle", () => {
+    const bus = new EventBus(noopLogger)
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier() })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "master", parentID: null })
+    manager.toggle("inst", "master")
+    publishSession(bus, "inst", "session.deleted", { id: "master" })
+
+    // toggle is independent of the tree (survives deletion)
+    assert.equal(manager.isEnabled("inst", "master"), true)
+
+    manager.stop()
+  })
+})
+
+describe("AutoAcceptManager persistence", () => {
+  it("hydrates a persisted family root before processing queued permissions", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    let release!: () => void
+    const gate = new Promise<void>((resolve) => { release = resolve })
+    const persistence: AutoAcceptPersistence = {
+      async loadSessions() {
+        await gate
+        return [
+          { id: "root", parentId: null, yoloEnabled: true },
+          { id: "child", parentId: "root", yoloEnabled: false },
+        ]
+      },
+      async persist() {},
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier, persistence })
+    manager.start()
+    publishSession(bus, "inst", "session.updated", { id: "child", parentID: "root" })
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "permission", sessionID: "child" },
+    })
+    await flushMicrotasks()
+    assert.equal(replier.calls.length, 0)
+    release()
+    await manager.hydrateInstance("inst")
+    await flushMicrotasks()
+    assert.equal(manager.isEnabled("inst", "child"), true)
+    assert.equal(replier.calls.length, 1)
+    manager.stop()
+  })
+
+  it("persists before enabling memory and emitting feedback", async () => {
+    const bus = new EventBus(noopLogger)
+    const changes: Record<string, unknown>[] = []
+    bus.on("yolo.stateChanged", (event) => changes.push(event))
+    let release!: () => void
+    const gate = new Promise<void>((resolve) => { release = resolve })
+    const writes: unknown[][] = []
+    const persistence: AutoAcceptPersistence = {
+      async loadSessions() { return [{ id: "root", parentId: null, yoloEnabled: false }] },
+      async persist(...args) { writes.push(args); await gate },
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier(), persistence })
+    const toggle = manager.toggle("inst", "root")
+    await flushMicrotasks()
+    assert.deepEqual(writes, [["inst", "root", true, undefined]])
+    assert.equal(manager.isEnabled("inst", "root"), false)
+    assert.equal(changes.length, 0)
+    release()
+    assert.equal(await toggle, true)
+    assert.equal(manager.isEnabled("inst", "root"), true)
+    assert.equal(changes.length, 1)
+  })
+
+  it("serializes concurrent toggles", async () => {
+    const bus = new EventBus(noopLogger)
+    const writes: boolean[] = []
+    const persistence: AutoAcceptPersistence = {
+      async loadSessions() { return [{ id: "root", parentId: null, yoloEnabled: false }] },
+      async persist(_instanceId, _rootSessionId, enabled) { writes.push(enabled) },
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier(), persistence })
+    assert.deepEqual(await Promise.all([manager.toggle("inst", "root"), manager.toggle("inst", "root")]), [true, false])
+    assert.deepEqual(writes, [true, false])
+    assert.equal(manager.isEnabled("inst", "root"), false)
+  })
+
+  it("keeps queued permissions until a failed hydration can retry", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    let attempts = 0
+    const persistence: AutoAcceptPersistence = {
+      async loadSessions() {
+        if (++attempts === 1) throw new Error("temporary failure")
+        return [{ id: "root", parentId: null, yoloEnabled: true }]
+      },
+      async persist() {},
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier, persistence })
+    manager.start()
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "permission", sessionID: "root" },
+    })
+    await flushMicrotasks()
+    assert.equal(replier.calls.length, 0)
+    await manager.hydrateInstance("inst")
+    await flushMicrotasks()
+    assert.equal(replier.calls.length, 1)
+    manager.stop()
+  })
+
+  it("does not re-enable memory when a persisted toggle finishes after cleanup", async () => {
+    const bus = new EventBus(noopLogger)
+    const changes: Record<string, unknown>[] = []
+    bus.on("yolo.stateChanged", (event) => changes.push(event))
+    let release!: () => void
+    const gate = new Promise<void>((resolve) => { release = resolve })
+    let writes = 0
+    const persistence: AutoAcceptPersistence = {
+      async loadSessions() { return [{ id: "root", parentId: null, yoloEnabled: false }] },
+      async persist() { writes += 1; await gate },
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier(), persistence })
+    const toggle = manager.toggle("inst", "root")
+    const queued = manager.toggle("inst", "root")
+    await flushMicrotasks()
+    manager.clearInstance("inst")
+    release()
+    assert.equal(await toggle, false)
+    assert.equal(await queued, false)
+    assert.equal(writes, 1)
+    assert.equal(manager.isEnabled("inst", "root"), false)
+    assert.equal(changes.length, 0)
+  })
+
+  it("moves persisted Yolo state when late ancestry changes the family root", async () => {
+    const bus = new EventBus(noopLogger)
+    const writes: unknown[][] = []
+    const persistence: AutoAcceptPersistence = {
+      async loadSessions() {
+        return [
+          { id: "parent", parentId: null, workspaceId: "workspace", yoloEnabled: false },
+          { id: "child", parentId: null, workspaceId: "workspace", yoloEnabled: true },
+        ]
+      },
+      async persist(...args) { writes.push(args) },
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier(), persistence })
+    manager.start()
+    await manager.hydrateInstance("inst")
+    publishSession(bus, "inst", "session.updated", { id: "child", parentID: "parent", workspaceID: "workspace" })
+    await flushMicrotasks()
+    assert.equal(manager.isEnabled("inst", "parent"), true)
+    assert.deepEqual(writes, [
+      ["inst", "parent", true, "workspace"],
+      ["inst", "child", false, "workspace"],
+    ])
+    manager.stop()
+  })
+
+  it("does not re-enable a family when ancestry repeatedly changes during a disable", async () => {
+    const bus = new EventBus(noopLogger)
+    let releaseFirst!: () => void
+    let releaseSecond!: () => void
+    const firstGate = new Promise<void>((resolve) => { releaseFirst = resolve })
+    const secondGate = new Promise<void>((resolve) => { releaseSecond = resolve })
+    const writes: unknown[][] = []
+    const persistence: AutoAcceptPersistence = {
+      async loadSessions() {
+        return [
+          { id: "grandparent", parentId: null, workspaceId: "workspace", yoloEnabled: false },
+          { id: "parent", parentId: null, workspaceId: "workspace", yoloEnabled: false },
+          { id: "child", parentId: null, workspaceId: "workspace", yoloEnabled: true },
+        ]
+      },
+      async persist(...args) {
+        writes.push(args)
+        if (writes.length === 1) await firstGate
+        if (writes.length === 2) await secondGate
+      },
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier(), persistence })
+    manager.start()
+    await manager.hydrateInstance("inst")
+    const toggle = manager.toggle("inst", "child")
+    await flushMicrotasks()
+    publishSession(bus, "inst", "session.updated", { id: "child", parentID: "parent", workspaceID: "workspace" })
+    releaseFirst()
+    await flushMicrotasks()
+    publishSession(bus, "inst", "session.updated", { id: "child", parentID: "grandparent", workspaceID: "workspace" })
+    releaseSecond()
+    assert.equal(await toggle, false)
+    await flushMicrotasks()
+    assert.equal(manager.isEnabled("inst", "grandparent"), false)
+    assert.equal(writes.some(([, , enabled]) => enabled === true), false, JSON.stringify(writes))
+    manager.stop()
+  })
+
+  it("allows a queued toggle to continue after an earlier persistence failure", async () => {
+    const bus = new EventBus(noopLogger)
+    let attempts = 0
+    const persistence: AutoAcceptPersistence = {
+      async loadSessions() { return [{ id: "root", parentId: null, yoloEnabled: false }] },
+      async persist() { if (++attempts === 1) throw new Error("write failed") },
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier(), persistence })
+    const first = manager.toggle("inst", "root")
+    const second = manager.toggle("inst", "root")
+    await assert.rejects(Promise.resolve(first), /write failed/)
+    assert.equal(await second, true)
+    assert.equal(manager.isEnabled("inst", "root"), true)
+  })
+
+  it("does not restore a late hydration after workspace cleanup", async () => {
+    const bus = new EventBus(noopLogger)
+    let release!: () => void
+    const gate = new Promise<void>((resolve) => { release = resolve })
+    const persistence: AutoAcceptPersistence = {
+      async loadSessions() { await gate; return [{ id: "root", parentId: null, yoloEnabled: true }] },
+      async persist() {},
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier(), persistence })
+    const hydration = manager.hydrateInstance("inst")
+    manager.clearInstance("inst")
+    release()
+    await hydration
+    assert.equal(manager.isEnabled("inst", "root"), false)
+  })
+})
+
+describe("AutoAcceptManager permission interception", () => {
+  it("auto-replies to a v2 permission on an enabled family", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const accepted: Record<string, unknown>[] = []
+    bus.on("yolo.autoAccepted", (e) => accepted.push(e))
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "master", parentID: null })
+    publishSession(bus, "inst", "session.updated", { id: "child", parentID: "master" })
+    manager.toggle("inst", "child") // enable the whole family root
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-1", sessionID: "child", action: "edit", resources: ["a.ts"] },
+    })
+
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 1)
+    const call = replier.calls[0]
+    assert.equal(call.instanceId, "inst")
+    assert.equal(call.permissionId, "perm-1")
+    assert.equal(call.sessionId, "child")
+    assert.equal(call.source, "v2")
+    assert.equal(call.reply, "once")
+    assert.equal(accepted.length, 1)
+    assert.equal((accepted[0] as any).permissionId, "perm-1")
+
+    manager.stop()
+  })
+
+  it("auto-replies to a legacy permission.asked event", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.asked",
+      properties: { id: "perm-2", sessionID: "solo", type: "bash" },
+    })
+
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 1)
+    assert.equal(replier.calls[0].source, "legacy")
+    assert.equal(replier.calls[0].permissionId, "perm-2")
+
+    manager.stop()
+  })
+
+  it("does not reply when the family is disabled", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-3", sessionID: "solo" },
+    })
+
+    await flushMicrotasks()
+    assert.equal(replier.calls.length, 0)
+
+    manager.stop()
+  })
+
+  it("ignores permission events without an id or sessionID", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+
+    publishInstanceEvent(bus, "inst", { type: "permission.v2.asked", properties: { sessionID: "solo" } })
+    publishInstanceEvent(bus, "inst", { type: "permission.v2.asked", properties: { id: "x" } })
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 0)
+    manager.stop()
+  })
+
+  it("deduplicates repeated emission of the same permission", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+
+    for (let i = 0; i < 3; i++) {
+      publishInstanceEvent(bus, "inst", {
+        type: "permission.v2.asked",
+        properties: { id: "perm-dup", sessionID: "solo" },
+      })
+    }
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 1)
+    manager.stop()
+  })
+
+  it("clears in-flight tracking after the reply resolves so it can retry", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-retry", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-retry", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 2)
+    manager.stop()
+  })
+})
+
+describe("AutoAcceptManager state events", () => {
+  it("publishes yolo.stateChanged with the new enabled value on toggle", () => {
+    const bus = new EventBus(noopLogger)
+    const changes: Record<string, unknown>[] = []
+    bus.on("yolo.stateChanged", (e) => changes.push(e))
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier() })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "master", parentID: null })
+
+    manager.toggle("inst", "master")
+    manager.toggle("inst", "master")
+
+    assert.equal(changes.length, 2)
+    assert.equal((changes[0] as any).enabled, true)
+    assert.equal((changes[1] as any).enabled, false)
+    assert.equal((changes[0] as any).sessionId, "master")
+    assert.equal((changes[0] as any).instanceId, "inst")
+
+    manager.stop()
+  })
+})
+
+describe("AutoAcceptManager lifecycle", () => {
+  it("clearInstance drops tree and enabled state for the instance", () => {
+    const bus = new EventBus(noopLogger)
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier() })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "master", parentID: null })
+    manager.toggle("inst", "master")
+    manager.clearInstance("inst")
+
+    assert.equal(manager.isEnabled("inst", "master"), false)
+    manager.stop()
+  })
+
+  it("clears state when the workspace stops", () => {
+    const bus = new EventBus(noopLogger)
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier() })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "master", parentID: null })
+    manager.toggle("inst", "master")
+    bus.publish({ type: "workspace.stopped", workspaceId: "inst" })
+
+    assert.equal(manager.isEnabled("inst", "master"), false)
+    manager.stop()
+  })
+
+  it("stop() unsubscribes so no further events are processed", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+    manager.stop()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "p", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 0)
+  })
+})
+
+describe("AutoAcceptManager pending permissions drain", () => {
+  it("drains a pending permission that arrived before enable", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+
+    // permission arrives while yolo is OFF
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-pending", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+    assert.equal(replier.calls.length, 0)
+
+    // enabling yolo should drain the pending permission
+    manager.toggle("inst", "solo")
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 1)
+    assert.equal(replier.calls[0].permissionId, "perm-pending")
+
+    manager.stop()
+  })
+
+  it("drains pending permissions for the same family only", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "root-a", parentID: null })
+    publishSession(bus, "inst", "session.updated", { id: "root-b", parentID: null })
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-a", sessionID: "root-a" },
+    })
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-b", sessionID: "root-b" },
+    })
+    await flushMicrotasks()
+    assert.equal(replier.calls.length, 0)
+
+    manager.toggle("inst", "root-a")
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 1)
+    assert.equal(replier.calls[0].permissionId, "perm-a")
+
+    manager.stop()
+  })
+
+  it("does not re-drain already-auto-accepted permissions", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-1", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+    assert.equal(replier.calls.length, 1)
+
+    // toggling off then on should not re-drain the already-replied permission
+    manager.toggle("inst", "solo") // off
+    manager.toggle("inst", "solo") // on — drain runs but pending set is empty
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 1)
+
+    manager.stop()
+  })
+
+  it("re-drains pending when late session ancestry joins an enabled family", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    // master exists, yolo enabled on master
+    publishSession(bus, "inst", "session.updated", { id: "master", parentID: null })
+    manager.toggle("inst", "master")
+
+    // child permission arrives BEFORE child's session ancestry is known.
+    // At this point "child" is unknown to the tree, so it resolves as its
+    // own root and the permission is NOT auto-accepted.
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-late", sessionID: "child" },
+    })
+    await flushMicrotasks()
+    assert.equal(replier.calls.length, 0)
+
+    // child session ancestry arrives — child.parentID = "master".
+    // ingestSession → upsertSession → migrateEnabledRoots makes "child"
+    // resolve to "master" (enabled). drainPending should fire and accept
+    // the previously-pending permission.
+    publishSession(bus, "inst", "session.updated", { id: "child", parentID: "master" })
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 1)
+    assert.equal(replier.calls[0].permissionId, "perm-late")
+    assert.equal(replier.calls[0].sessionId, "child")
+
+    manager.stop()
+  })
+})
+
+describe("AutoAcceptManager permission replied cleanup", () => {
+  it("removes a pending permission on permission.v2.replied", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-x", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+
+    // user manually replies → replied event cleans up pending
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.replied",
+      properties: { id: "perm-x" },
+    })
+
+    // enabling yolo now should NOT drain the already-replied permission
+    manager.toggle("inst", "solo")
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 0)
+    manager.stop()
+  })
+
+  it("removes a pending permission on legacy permission.replied", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.asked",
+      properties: { id: "perm-y", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.replied",
+      properties: { requestID: "perm-y" },
+    })
+
+    manager.toggle("inst", "solo")
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 0)
+    manager.stop()
+  })
+})
+
+describe("AutoAcceptManager clearInstance clears pending", () => {
+  it("drops pending permissions on clearInstance", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-z", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+
+    manager.clearInstance("inst")
+
+    // re-create session and enable — pending set should be empty
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 0)
+    manager.stop()
+  })
+})
+
+describe("AutoAcceptManager permission.updated source inference", () => {
+  it("preserves the original v2 source when permission.updated arrives", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    // yolo is OFF — permission goes to pending with source "v2"
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-v2", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+
+    // enable yolo, then send permission.updated — should keep source "v2"
+    manager.toggle("inst", "solo")
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.updated",
+      properties: { id: "perm-v2", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 1)
+    assert.equal(replier.calls[0].source, "v2")
+
+    manager.stop()
+  })
+
+  it("skips permission.updated for a permission not in pending", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+
+    // permission.updated for a permission that was never asked (not in pending)
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.updated",
+      properties: { id: "perm-unknown", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 0)
+    manager.stop()
+  })
+})
+
+describe("AutoAcceptManager replier failure handling", () => {
+  it("keeps permission pending and does not emit autoAccepted on failure", async () => {
+    const bus = new EventBus(noopLogger)
+    const autoAccepted: unknown[] = []
+    bus.on("yolo.autoAccepted", (e) => autoAccepted.push(e))
+    const failingReplier: PermissionReplier = async () => {
+      throw new Error("connection refused")
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: failingReplier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-fail", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+
+    assert.equal(autoAccepted.length, 0)
+    // permission should still be pending (enabling again would try again)
+    manager.toggle("inst", "solo") // off
+    manager.toggle("inst", "solo") // on — drain retries
+    await flushMicrotasks()
+
+    assert.equal(autoAccepted.length, 0)
+
+    manager.stop()
+  })
+
+  it("stops retrying after MAX_REPLY_ATTEMPTS", async () => {
+    const bus = new EventBus(noopLogger)
+    let callCount = 0
+    const failingReplier: PermissionReplier = async () => {
+      callCount++
+      throw new Error("timeout")
+    }
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: failingReplier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-stuck", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+    const attemptsAfterFirst = callCount
+
+    // trigger drains via session events
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    await flushMicrotasks()
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    await flushMicrotasks()
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    await flushMicrotasks()
+
+    // should have attempted at most MAX_REPLY_ATTEMPTS times total
+    assert.ok(callCount <= 3, `expected at most 3 attempts, got ${callCount}`)
+    assert.equal(callCount, attemptsAfterFirst + 2) // 2 more retries (total 3), then stops
+
+    manager.stop()
+  })
+})
+
+describe("AutoAcceptManager workspace.error cleanup", () => {
+  it("clears state when the workspace errors", () => {
+    const bus = new EventBus(noopLogger)
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier: makeRecordingReplier() })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+    manager.toggle("inst", "solo")
+    assert.equal(manager.isEnabled("inst", "solo"), true)
+
+    bus.publish({ type: "workspace.error", workspace: { id: "inst" } as any })
+
+    assert.equal(manager.isEnabled("inst", "solo"), false)
+    manager.stop()
+  })
+})
+
+describe("AutoAcceptManager session.deleted clears pending", () => {
+  it("removes pending permissions for a deleted session", async () => {
+    const bus = new EventBus(noopLogger)
+    const replier = makeRecordingReplier()
+    const manager = new AutoAcceptManager({ eventBus: bus, logger: noopLogger, replier })
+    manager.start()
+
+    publishSession(bus, "inst", "session.updated", { id: "solo", parentID: null })
+
+    // permission arrives while yolo is OFF → goes to pending
+    publishInstanceEvent(bus, "inst", {
+      type: "permission.v2.asked",
+      properties: { id: "perm-doomed", sessionID: "solo" },
+    })
+    await flushMicrotasks()
+
+    // session deleted → pending should be cleared
+    publishSession(bus, "inst", "session.deleted", { id: "solo" })
+
+    // enabling yolo should not drain the deleted session's permission
+    manager.toggle("inst", "solo")
+    await flushMicrotasks()
+
+    assert.equal(replier.calls.length, 0)
+    manager.stop()
+  })
+})
+
+function makeRecordingReplier() {
+  const calls: AutoAcceptReply[] = []
+  const replier: PermissionReplier = async (reply) => {
+    calls.push(reply)
+  }
+  return Object.assign(replier, { calls }) as PermissionReplier & { calls: AutoAcceptReply[] }
+}
+
+function flushMicrotasks() {
+  return new Promise<void>((resolve) => setImmediate(resolve))
+}
diff --git a/packages/server/src/permissions/auto-accept-manager.ts b/packages/server/src/permissions/auto-accept-manager.ts
new file mode 100644
index 00000000..3fc7e7e6
--- /dev/null
+++ b/packages/server/src/permissions/auto-accept-manager.ts
@@ -0,0 +1,475 @@
+import type { EventBus } from "../events/bus"
+import type { Logger } from "../logger"
+import { AutoAcceptStore, type AutoAcceptSessionInfo } from "./auto-accept-store"
+
+/**
+ * Server-side owner of Yolo (permission auto-accept).
+ *
+ * Subscribes to the instance SSE stream that the server already consumes
+ * (`InstanceEventBridge` -> EventBus `instance.event`) and:
+ *   - maintains a per-instance session tree so family-root inheritance can
+ *     be resolved identically to the previous frontend implementation
+ *   - when a permission request arrives for an enabled family, auto-replies
+ *     via the injected {@link PermissionReplier} (same `"once"` semantics the
+ *     UI used to send)
+ *   - emits `yolo.stateChanged` / `yolo.autoAccepted` events on the EventBus
+ *     so the UI stays a pure view
+ */
+
+export type PermissionSource = "v2" | "legacy"
+export type PermissionReplyValue = "once"
+
+export interface AutoAcceptReply {
+  instanceId: string
+  permissionId: string
+  sessionId: string
+  source: PermissionSource
+  reply: PermissionReplyValue
+}
+
+export type PermissionReplier = (reply: AutoAcceptReply) => Promise<void>
+
+interface PendingPermission {
+  permissionId: string
+  sessionId: string
+  source: PermissionSource
+}
+
+interface AutoAcceptManagerDeps {
+  eventBus: EventBus
+  logger: Logger
+  replier: PermissionReplier
+  persistence?: AutoAcceptPersistence
+}
+
+export interface PersistedAutoAcceptSession extends AutoAcceptSessionInfo {
+  yoloEnabled: boolean
+  workspaceId?: string
+}
+
+export interface AutoAcceptPersistence {
+  loadSessions(instanceId: string): Promise<PersistedAutoAcceptSession[]>
+  persist(instanceId: string, rootSessionId: string, enabled: boolean, workspaceId?: string): Promise<void>
+}
+
+const PERMISSION_ASK_TYPES = new Set(["permission.v2.asked", "permission.asked", "permission.updated"])
+const PERMISSION_REPLIED_TYPES = new Set(["permission.v2.replied", "permission.replied"])
+const SESSION_UPSERT_TYPES = new Set(["session.updated", "session.created"])
+const SESSION_REMOVE_TYPES = new Set(["session.deleted"])
+
+export class AutoAcceptManager {
+  private static readonly MAX_REPLY_ATTEMPTS = 3
+  private readonly store = new AutoAcceptStore()
+  /** instanceId:permissionId entries currently being replied, to dedupe re-emissions */
+  private readonly inFlight = new Set<string>()
+  /** instanceId -> (permissionId -> pending permission) awaiting a reply */
+  private readonly pending = new Map<string, Map<string, PendingPermission>>()
+  /** instanceId:permissionId -> failure count, to stop retrying stuck permissions */
+  private readonly replyAttempts = new Map<string, number>()
+  private readonly hydratedInstances = new Set<string>()
+  private readonly hydration = new Map<string, Promise<void>>()
+  private readonly queuedEvents = new Map<string, InstanceStreamPayload[]>()
+  private readonly instanceGeneration = new Map<string, number>()
+  private readonly sessionWorkspaces = new Map<string, Map<string, string>>()
+  private readonly mutations = new Map<string, Promise<boolean>>()
+  private unsubscribe?: () => void
+
+  constructor(private readonly deps: AutoAcceptManagerDeps) {}
+
+  start(): void {
+    if (this.unsubscribe) return
+    const handler = (payload: { instanceId?: string; event?: InstanceStreamPayload }) => {
+      if (!payload || !payload.instanceId || !payload.event) return
+      if (this.deps.persistence && !this.hydratedInstances.has(payload.instanceId)) {
+        const queued = this.queuedEvents.get(payload.instanceId) ?? []
+        queued.push(payload.event)
+        this.queuedEvents.set(payload.instanceId, queued)
+        void this.hydrateInstance(payload.instanceId).catch((error) => {
+          this.deps.logger.warn({ instanceId: payload.instanceId, err: error }, "Failed to hydrate persisted Yolo state")
+        })
+        return
+      }
+      this.handleInstanceEvent(payload.instanceId, payload.event)
+    }
+    const onStarted = (event: { workspace?: { id?: string } }) => {
+      const instanceId = event.workspace?.id
+      if (!instanceId) return
+      void this.hydrateInstance(instanceId).catch((error) => {
+        this.deps.logger.warn({ instanceId, err: error }, "Failed to hydrate persisted Yolo state")
+      })
+    }
+    const onStopped = (event: { workspaceId?: string }) => {
+      if (event?.workspaceId) this.clearInstance(event.workspaceId)
+    }
+    const onError = (event: { workspace?: { id?: string } }) => {
+      if (event?.workspace?.id) this.clearInstance(event.workspace.id)
+    }
+    this.deps.eventBus.on("instance.event", handler)
+    this.deps.eventBus.on("workspace.started", onStarted)
+    this.deps.eventBus.on("workspace.stopped", onStopped)
+    this.deps.eventBus.on("workspace.error", onError)
+    this.unsubscribe = () => {
+      this.deps.eventBus.off("instance.event", handler)
+      this.deps.eventBus.off("workspace.started", onStarted)
+      this.deps.eventBus.off("workspace.stopped", onStopped)
+      this.deps.eventBus.off("workspace.error", onError)
+    }
+  }
+
+  stop(): void {
+    this.unsubscribe?.()
+    this.unsubscribe = undefined
+  }
+
+  isEnabled(instanceId: string, sessionId: string): boolean {
+    return this.store.isEnabled(instanceId, sessionId)
+  }
+
+  hydrateInstance(instanceId: string): Promise<void> {
+    if (!this.deps.persistence || this.hydratedInstances.has(instanceId)) return Promise.resolve()
+    const existing = this.hydration.get(instanceId)
+    if (existing) return existing
+    const generation = this.instanceGeneration.get(instanceId) ?? 0
+    let hydrated = false
+    const pending = this.deps.persistence.loadSessions(instanceId).then((sessions) => {
+      if ((this.instanceGeneration.get(instanceId) ?? 0) !== generation) return
+      this.store.clearInstance(instanceId)
+      const workspaces = new Map<string, string>()
+      for (const session of sessions) {
+        this.store.upsertSession(instanceId, session)
+        if (session.workspaceId) workspaces.set(session.id, session.workspaceId)
+      }
+      this.sessionWorkspaces.set(instanceId, workspaces)
+      for (const session of sessions) {
+        if (!session.yoloEnabled || this.store.familyRoot(instanceId, session.id) !== session.id) continue
+        this.store.setEnabled(instanceId, session.id, true)
+        this.deps.eventBus.publish({ type: "yolo.stateChanged", instanceId, sessionId: session.id, enabled: true })
+        this.drainPending(instanceId, session.id)
+      }
+      this.hydratedInstances.add(instanceId)
+      hydrated = true
+    }).finally(() => {
+      if ((this.instanceGeneration.get(instanceId) ?? 0) !== generation) return
+      this.hydration.delete(instanceId)
+      if (!hydrated) return
+      const queued = this.queuedEvents.get(instanceId) ?? []
+      this.queuedEvents.delete(instanceId)
+      for (const event of queued) this.handleInstanceEvent(instanceId, event)
+    })
+    this.hydration.set(instanceId, pending)
+    return pending
+  }
+
+  toggle(instanceId: string, sessionId: string): boolean | Promise<boolean> {
+    if (this.deps.persistence) return this.togglePersisted(instanceId, sessionId)
+    const enabled = this.store.toggle(instanceId, sessionId)
+    this.deps.eventBus.publish({ type: "yolo.stateChanged", instanceId, sessionId, enabled })
+    if (enabled) {
+      this.drainPending(instanceId, sessionId)
+    }
+    return enabled
+  }
+
+  private async togglePersisted(instanceId: string, sessionId: string): Promise<boolean> {
+    await this.hydrateInstance(instanceId)
+    const generation = this.instanceGeneration.get(instanceId) ?? 0
+    const mutation = (this.mutations.get(instanceId) ?? Promise.resolve(false)).catch(() => false).then(async () => {
+      if ((this.instanceGeneration.get(instanceId) ?? 0) !== generation) {
+        return this.store.isEnabled(instanceId, sessionId)
+      }
+      const rootSessionId = this.store.familyRoot(instanceId, sessionId)
+      const traversedRootSessionIds = new Set([rootSessionId])
+      const enabled = !this.store.isEnabled(instanceId, rootSessionId)
+      await this.deps.persistence!.persist(
+        instanceId,
+        rootSessionId,
+        enabled,
+        this.sessionWorkspaces.get(instanceId)?.get(rootSessionId),
+      )
+      if ((this.instanceGeneration.get(instanceId) ?? 0) !== generation) {
+        return this.store.isEnabled(instanceId, rootSessionId)
+      }
+      let persistedRootSessionId = rootSessionId
+      let currentRootSessionId = this.store.familyRoot(instanceId, sessionId)
+      while (currentRootSessionId !== persistedRootSessionId) {
+        traversedRootSessionIds.add(currentRootSessionId)
+        await this.deps.persistence!.persist(
+          instanceId,
+          currentRootSessionId,
+          enabled,
+          this.sessionWorkspaces.get(instanceId)?.get(currentRootSessionId),
+        )
+        if (enabled) {
+          await this.deps.persistence!.persist(
+            instanceId,
+            persistedRootSessionId,
+            false,
+            this.sessionWorkspaces.get(instanceId)?.get(persistedRootSessionId),
+          )
+        }
+        persistedRootSessionId = currentRootSessionId
+        currentRootSessionId = this.store.familyRoot(instanceId, sessionId)
+      }
+      if ((this.instanceGeneration.get(instanceId) ?? 0) !== generation) {
+        return this.store.isEnabled(instanceId, currentRootSessionId)
+      }
+      if (enabled) {
+        this.store.setEnabled(instanceId, currentRootSessionId, true)
+      } else {
+        for (const traversedRootSessionId of traversedRootSessionIds) {
+          this.store.setEnabled(instanceId, traversedRootSessionId, false)
+        }
+      }
+      this.deps.eventBus.publish({ type: "yolo.stateChanged", instanceId, sessionId: currentRootSessionId, enabled })
+      if (enabled) this.drainPending(instanceId, currentRootSessionId)
+      return enabled
+    })
+    const settled = mutation.finally(() => {
+      if (this.mutations.get(instanceId) === settled) this.mutations.delete(instanceId)
+    })
+    this.mutations.set(instanceId, settled)
+    return settled
+  }
+
+  clearInstance(instanceId: string): void {
+    this.instanceGeneration.set(instanceId, (this.instanceGeneration.get(instanceId) ?? 0) + 1)
+    this.hydratedInstances.delete(instanceId)
+    this.hydration.delete(instanceId)
+    this.queuedEvents.delete(instanceId)
+    this.sessionWorkspaces.delete(instanceId)
+    this.mutations.delete(instanceId)
+    this.store.clearInstance(instanceId)
+    this.pending.delete(instanceId)
+    const prefix = `${instanceId}:`
+    for (const key of Array.from(this.inFlight.keys())) {
+      if (key.startsWith(prefix)) this.inFlight.delete(key)
+    }
+    for (const key of Array.from(this.replyAttempts.keys())) {
+      if (key.startsWith(prefix)) this.replyAttempts.delete(key)
+    }
+  }
+
+  handleInstanceEvent(instanceId: string, event: InstanceStreamPayload): void {
+    if (!event || typeof event.type !== "string") return
+
+    if (SESSION_UPSERT_TYPES.has(event.type)) {
+      this.ingestSession(instanceId, event.properties)
+      return
+    }
+    if (SESSION_REMOVE_TYPES.has(event.type)) {
+      const info = (event.properties as { info?: SessionProperties } | undefined)?.info
+      const id = readString(info?.id) ?? readString(event.properties?.id)
+      if (id) {
+        this.store.removeSession(instanceId, id)
+        this.removePendingForSession(instanceId, id)
+      }
+      return
+    }
+    if (PERMISSION_REPLIED_TYPES.has(event.type)) {
+      this.handlePermissionReplied(instanceId, event.properties)
+      return
+    }
+    if (PERMISSION_ASK_TYPES.has(event.type)) {
+      this.handlePermissionRequest(instanceId, event.type, event.properties)
+    }
+  }
+
+  private ingestSession(instanceId: string, properties: unknown): void {
+    // OpenCode wraps session records under `properties.info` for
+    // session.created/updated/deleted (see SDK EventSessionUpdated). Accept a
+    // flat fallback only for defensive compatibility.
+    const info = (properties as { info?: SessionProperties } | SessionProperties | undefined)
+    const session = (info && typeof info === "object" && "info" in info ? info.info : info) as
+      | SessionProperties
+      | undefined
+    if (!session || typeof session.id !== "string") return
+    const parentId = session.parentID ?? session.parentId ?? null
+    const revert = session.revert ?? undefined
+    const enabledBefore = this.store.enabledRoots(instanceId)
+    this.store.upsertSession(instanceId, { id: session.id, parentId, revert })
+    if (typeof session.workspaceID === "string" && session.workspaceID) {
+      const workspaces = this.sessionWorkspaces.get(instanceId) ?? new Map<string, string>()
+      workspaces.set(session.id, session.workspaceID)
+      this.sessionWorkspaces.set(instanceId, workspaces)
+    }
+    this.persistRootMigration(instanceId, enabledBefore, this.store.enabledRoots(instanceId))
+    // Session ancestry may have changed (parent discovered, revert toggled).
+    // Re-drain pending permissions whose family root may have migrated into
+    // an enabled family — mirrors the old UI's drainAutoAcceptPermissions-
+    // ForInstance trigger on session.updated (#497).
+    this.drainPending(instanceId, session.id)
+  }
+
+  private persistRootMigration(instanceId: string, before: readonly string[], after: readonly string[]): void {
+    if (!this.deps.persistence) return
+    const removed = before.filter((id) => !after.includes(id))
+    const added = after.filter((id) => !before.includes(id))
+    if (removed.length === 0 && added.length === 0) return
+    const generation = this.instanceGeneration.get(instanceId) ?? 0
+    const mutation = (this.mutations.get(instanceId) ?? Promise.resolve(false)).catch(() => false).then(async () => {
+      if ((this.instanceGeneration.get(instanceId) ?? 0) !== generation) return false
+      const enabledRoots = new Set(this.store.enabledRoots(instanceId))
+      for (const rootSessionId of added) {
+        if (!enabledRoots.has(rootSessionId)) continue
+        await this.deps.persistence!.persist(
+          instanceId, rootSessionId, true, this.sessionWorkspaces.get(instanceId)?.get(rootSessionId),
+        )
+      }
+      for (const rootSessionId of removed) {
+        if (enabledRoots.has(rootSessionId)) continue
+        if ((this.instanceGeneration.get(instanceId) ?? 0) !== generation) return false
+        await this.deps.persistence!.persist(
+          instanceId, rootSessionId, false, this.sessionWorkspaces.get(instanceId)?.get(rootSessionId),
+        )
+      }
+      return false
+    })
+    const settled = mutation.finally(() => {
+      if (this.mutations.get(instanceId) === settled) this.mutations.delete(instanceId)
+    })
+    this.mutations.set(instanceId, settled)
+    void settled.catch((error) => {
+      this.deps.logger.warn({ instanceId, err: error }, "Failed to migrate persisted Yolo family root")
+    })
+  }
+
+  private handlePermissionRequest(instanceId: string, eventType: string, permission: unknown): void {
+    const request = permission as PermissionProperties | undefined
+    if (!request) return
+    const permissionId = readString(request.id)
+    const sessionId = readString(request.sessionID) ?? readString(request.sessionId)
+    if (!permissionId || !sessionId) return
+
+    // Infer source from the event type, but prefer the already-tracked source
+    // for permission.updated (which may belong to a v2 permission).
+    const existing = this.pending.get(instanceId)?.get(permissionId)
+    const source: PermissionSource = eventType === "permission.v2.asked" ? "v2" : (existing?.source ?? "legacy")
+
+    // `permission.updated` represents a detail change for a permission that
+    // is *already* pending. If it is no longer in our pending set it was
+    // already replied to (by us or the user) — skip to avoid a duplicate reply.
+    if (eventType === "permission.updated" && !this.pending.get(instanceId)?.has(permissionId)) {
+      return
+    }
+
+    this.addPending(instanceId, { permissionId, sessionId, source })
+
+    if (!this.store.isEnabled(instanceId, sessionId)) return
+    this.tryAutoAccept(instanceId, permissionId, sessionId, source)
+  }
+
+  private handlePermissionReplied(instanceId: string, properties: unknown): void {
+    const request = (properties as PermissionRepliedProperties | undefined) ?? {}
+    const permissionId =
+      readString(request.id) ??
+      readString(request.requestID) ??
+      readString(request.permissionID) ??
+      readString(request.requestId) ??
+      readString(request.permissionId)
+    if (permissionId) this.removePending(instanceId, permissionId)
+  }
+
+  private tryAutoAccept(
+    instanceId: string,
+    permissionId: string,
+    sessionId: string,
+    source: PermissionSource,
+  ): void {
+    const key = `${instanceId}:${permissionId}`
+    if (this.inFlight.has(key)) return
+    const attempts = this.replyAttempts.get(key) ?? 0
+    if (attempts >= AutoAcceptManager.MAX_REPLY_ATTEMPTS) return
+    this.inFlight.add(key)
+    this.replyAttempts.set(key, attempts + 1)
+
+    const reply: AutoAcceptReply = { instanceId, permissionId, sessionId, source, reply: "once" }
+
+    void this.deps.replier(reply)
+      .then(() => {
+        this.replyAttempts.delete(key)
+        this.removePending(instanceId, permissionId)
+        this.deps.eventBus.publish({ type: "yolo.autoAccepted", instanceId, sessionId, permissionId })
+      })
+      .catch((error) => {
+        this.deps.logger.error({ instanceId, permissionId, err: error, attempt: attempts + 1 }, "Yolo auto-accept reply failed")
+        if (attempts + 1 >= AutoAcceptManager.MAX_REPLY_ATTEMPTS) {
+          this.removePending(instanceId, permissionId)
+        }
+      })
+      .finally(() => {
+        this.inFlight.delete(key)
+      })
+  }
+
+  /** Auto-accept all pending permissions belonging to the same family root. */
+  private drainPending(instanceId: string, sessionId: string): void {
+    const instancePending = this.pending.get(instanceId)
+    if (!instancePending || instancePending.size === 0) return
+    const root = this.store.familyRoot(instanceId, sessionId)
+    for (const entry of Array.from(instancePending.values())) {
+      if (this.store.familyRoot(instanceId, entry.sessionId) === root) {
+        this.tryAutoAccept(instanceId, entry.permissionId, entry.sessionId, entry.source)
+      }
+    }
+  }
+
+  private addPending(instanceId: string, entry: PendingPermission): void {
+    let instancePending = this.pending.get(instanceId)
+    if (!instancePending) {
+      instancePending = new Map()
+      this.pending.set(instanceId, instancePending)
+    }
+    instancePending.set(entry.permissionId, entry)
+  }
+
+  private removePending(instanceId: string, permissionId: string): void {
+    const instancePending = this.pending.get(instanceId)
+    if (instancePending?.delete(permissionId)) {
+      this.replyAttempts.delete(`${instanceId}:${permissionId}`)
+      if (instancePending.size === 0) this.pending.delete(instanceId)
+    }
+  }
+
+  private removePendingForSession(instanceId: string, sessionId: string): void {
+    const instancePending = this.pending.get(instanceId)
+    if (!instancePending) return
+    for (const [permId, entry] of Array.from(instancePending)) {
+      if (entry.sessionId === sessionId) {
+        instancePending.delete(permId)
+        this.replyAttempts.delete(`${instanceId}:${permId}`)
+      }
+    }
+    if (instancePending.size === 0) this.pending.delete(instanceId)
+  }
+}
+
+interface InstanceStreamPayload {
+  type?: string
+  properties?: Record<string, unknown>
+}
+
+interface SessionProperties {
+  id?: string
+  parentID?: string | null
+  parentId?: string | null
+  revert?: unknown
+  workspaceID?: string
+}
+
+interface PermissionProperties {
+  id?: string
+  sessionID?: string
+  sessionId?: string
+}
+
+interface PermissionRepliedProperties {
+  id?: string
+  requestID?: string
+  permissionID?: string
+  requestId?: string
+  permissionId?: string
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined
+}
diff --git a/packages/server/src/permissions/auto-accept-store.test.ts b/packages/server/src/permissions/auto-accept-store.test.ts
new file mode 100644
index 00000000..5ccfd540
--- /dev/null
+++ b/packages/server/src/permissions/auto-accept-store.test.ts
@@ -0,0 +1,182 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { AutoAcceptStore, resolveFamilyRoot } from "./auto-accept-store"
+
+describe("resolveFamilyRoot", () => {
+  it("returns the session id itself when no info is known", () => {
+    assert.equal(resolveFamilyRoot("orphan", () => undefined), "orphan")
+  })
+
+  it("keeps a loaded child as root when its parent is missing", () => {
+    const root = resolveFamilyRoot("child", (id) =>
+      id === "child" ? { id: "child", parentId: "parent" } : undefined,
+    )
+    assert.equal(root, "child")
+  })
+
+  it("resolves to the master session when the full parent chain is loaded", () => {
+    const root = resolveFamilyRoot("grandchild", (id) => {
+      if (id === "grandchild") return { id: "grandchild", parentId: "child" }
+      if (id === "child") return { id: "child", parentId: "master" }
+      if (id === "master") return { id: "master", parentId: null }
+      return undefined
+    })
+    assert.equal(root, "master")
+  })
+
+  it("keeps a fork session (with revert) as its own root", () => {
+    const root = resolveFamilyRoot("fork", (id) => {
+      if (id === "fork")
+        return { id: "fork", parentId: "master", revert: { messageID: "msg", partID: "part" } }
+      if (id === "master") return { id: "master", parentId: null }
+      return undefined
+    })
+    assert.equal(root, "fork")
+  })
+
+  it("terminates on cyclic parent chains without looping forever", () => {
+    const root = resolveFamilyRoot("a", (id) => {
+      if (id === "a") return { id: "a", parentId: "b" }
+      if (id === "b") return { id: "b", parentId: "a" }
+      return undefined
+    })
+    // cycle: last known id before re-entering the cycle is returned
+    assert.ok(root === "a" || root === "b")
+  })
+})
+
+describe("AutoAcceptStore inheritance", () => {
+  it("is disabled by default for an unknown session", () => {
+    const store = new AutoAcceptStore()
+    assert.equal(store.isEnabled("inst", "s1"), false)
+  })
+
+  it("enabling a parent enables every descendant that resolves to it", () => {
+    const store = new AutoAcceptStore()
+    store.upsertSession("inst", { id: "master", parentId: null })
+    store.upsertSession("inst", { id: "child", parentId: "master" })
+    store.upsertSession("inst", { id: "grandchild", parentId: "child" })
+
+    store.setEnabled("inst", "master", true)
+
+    assert.equal(store.isEnabled("inst", "master"), true)
+    assert.equal(store.isEnabled("inst", "child"), true)
+    assert.equal(store.isEnabled("inst", "grandchild"), true)
+  })
+
+  it("enabling a child also covers the parent family root and siblings", () => {
+    const store = new AutoAcceptStore()
+    store.upsertSession("inst", { id: "master", parentId: null })
+    store.upsertSession("inst", { id: "child-a", parentId: "master" })
+    store.upsertSession("inst", { id: "child-b", parentId: "master" })
+
+    store.setEnabled("inst", "child-a", true)
+
+    assert.equal(store.isEnabled("inst", "child-a"), true)
+    assert.equal(store.isEnabled("inst", "child-b"), true)
+    assert.equal(store.isEnabled("inst", "master"), true)
+  })
+
+  it("a fork session is isolated: enabling it does not enable its parent", () => {
+    const store = new AutoAcceptStore()
+    store.upsertSession("inst", { id: "master", parentId: null })
+    store.upsertSession("inst", {
+      id: "fork",
+      parentId: "master",
+      revert: { messageID: "msg", partID: "part" },
+    })
+
+    store.setEnabled("inst", "fork", true)
+
+    assert.equal(store.isEnabled("inst", "fork"), true)
+    assert.equal(store.isEnabled("inst", "master"), false)
+  })
+
+  it("disabling the family root clears the setting for all descendants", () => {
+    const store = new AutoAcceptStore()
+    store.upsertSession("inst", { id: "master", parentId: null })
+    store.upsertSession("inst", { id: "child", parentId: "master" })
+
+    store.setEnabled("inst", "child", true)
+    assert.equal(store.isEnabled("inst", "child"), true)
+
+    store.setEnabled("inst", "master", false)
+    assert.equal(store.isEnabled("inst", "child"), false)
+    assert.equal(store.isEnabled("inst", "master"), false)
+  })
+
+  it("toggle flips the resolved family-root state and reports the new value", () => {
+    const store = new AutoAcceptStore()
+    store.upsertSession("inst", { id: "master", parentId: null })
+    store.upsertSession("inst", { id: "child", parentId: "master" })
+
+    assert.equal(store.toggle("inst", "child"), true)
+    assert.equal(store.isEnabled("inst", "child"), true)
+    assert.equal(store.toggle("inst", "master"), false)
+    assert.equal(store.isEnabled("inst", "child"), false)
+  })
+
+  it("keeps per-instance state independent", () => {
+    const store = new AutoAcceptStore()
+    store.upsertSession("inst-a", { id: "root", parentId: null })
+    store.upsertSession("inst-b", { id: "root", parentId: null })
+
+    store.setEnabled("inst-a", "root", true)
+    assert.equal(store.isEnabled("inst-a", "root"), true)
+    assert.equal(store.isEnabled("inst-b", "root"), false)
+  })
+})
+
+describe("AutoAcceptStore session tree maintenance", () => {
+  it("migrates enabled root when a parent is discovered later", () => {
+    const store = new AutoAcceptStore()
+    store.upsertSession("inst", { id: "child", parentId: "parent" })
+    // parent unknown -> child is its own root
+    store.setEnabled("inst", "child", true)
+
+    // later the parent shows up — root should migrate from "child" to "parent"
+    store.upsertSession("inst", { id: "parent", parentId: null })
+    assert.equal(store.isEnabled("inst", "parent"), true)
+    assert.equal(store.isEnabled("inst", "child"), true)
+  })
+
+  it("removing a session does not clear an enabled family root", () => {
+    const store = new AutoAcceptStore()
+    store.upsertSession("inst", { id: "master", parentId: null })
+    store.setEnabled("inst", "master", true)
+    store.removeSession("inst", "master")
+    // the toggle is independent of the session tree: it survives session deletion
+    assert.equal(store.isEnabled("inst", "master"), true)
+  })
+
+  it("clearInstance drops both tree and enabled state", () => {
+    const store = new AutoAcceptStore()
+    store.upsertSession("inst", { id: "master", parentId: null })
+    store.setEnabled("inst", "master", true)
+    store.clearInstance("inst")
+    assert.equal(store.isEnabled("inst", "master"), false)
+    store.upsertSession("inst", { id: "master", parentId: null })
+    assert.equal(store.isEnabled("inst", "master"), false)
+  })
+
+  it("changing revert status re-roots a session as a fork", () => {
+    const store = new AutoAcceptStore()
+    store.upsertSession("inst", { id: "master", parentId: null })
+    store.upsertSession("inst", { id: "child", parentId: "master" })
+    store.setEnabled("inst", "child", true)
+    // parent family enabled
+    assert.equal(store.isEnabled("inst", "master"), true)
+
+    // child becomes a fork
+    store.upsertSession("inst", {
+      id: "child",
+      parentId: "master",
+      revert: { messageID: "m", partID: "p" },
+    })
+    // now child resolves to itself; the family setting was on "master" so still on for master
+    assert.equal(store.isEnabled("inst", "master"), true)
+    // child is its own root now, not enabled unless toggled
+    assert.equal(store.isEnabled("inst", "child"), false)
+  })
+})
diff --git a/packages/server/src/permissions/auto-accept-store.ts b/packages/server/src/permissions/auto-accept-store.ts
new file mode 100644
index 00000000..b53e6258
--- /dev/null
+++ b/packages/server/src/permissions/auto-accept-store.ts
@@ -0,0 +1,132 @@
+/**
+ * In-memory permission auto-accept (Yolo) state, owned by the server.
+ *
+ * This is a faithful port of the previous frontend implementation
+ * (`packages/ui/src/stores/permission-auto-accept.ts`) so the inheritance
+ * semantics are preserved exactly:
+ *   - state is keyed by the resolved *family root* session id
+ *   - a session with a `revert` snapshot is treated as its own root (fork)
+ *   - enabling any session enables its whole family root and vice-versa
+ *
+ * This store remains in-memory; AutoAcceptManager hydrates and persists it
+ * through OpenCode session metadata.
+ */
+
+export interface AutoAcceptSessionInfo {
+  id: string
+  parentId?: string | null
+  /** Truthy value marks the session as a fork that roots at itself. */
+  revert?: unknown
+}
+
+type SessionLookup = (sessionId: string) => AutoAcceptSessionInfo | undefined
+
+/**
+ * Resolve the family-root session id for `sessionId` by walking the parent
+ * chain. Mirrors `resolvePermissionAutoAcceptFamilyRoot` from the UI so
+ * inheritance behaviour does not change.
+ */
+export function resolveFamilyRoot(sessionId: string, getSession: SessionLookup): string {
+  let currentId = sessionId
+  let lastKnownId = sessionId
+  const seen = new Set<string>()
+
+  while (currentId && !seen.has(currentId)) {
+    seen.add(currentId)
+    const session = getSession(currentId)
+    if (!session) return lastKnownId
+    lastKnownId = session.id
+    if (session.revert) return session.id
+    if (!session.parentId) return session.id
+    currentId = session.parentId
+  }
+
+  return currentId || sessionId
+}
+
+export class AutoAcceptStore {
+  /** instanceId -> set of enabled family-root session ids */
+  private readonly enabled = new Map<string, Set<string>>()
+  /** instanceId -> (sessionId -> info) */
+  private readonly sessions = new Map<string, Map<string, AutoAcceptSessionInfo>>()
+
+  isEnabled(instanceId: string, sessionId: string): boolean {
+    const root = this.familyRoot(instanceId, sessionId)
+    return this.enabled.get(instanceId)?.has(root) ?? false
+  }
+
+  setEnabled(instanceId: string, sessionId: string, enabled: boolean): void {
+    const root = this.familyRoot(instanceId, sessionId)
+    let roots = this.enabled.get(instanceId)
+    if (!roots) {
+      if (!enabled) return
+      roots = new Set()
+      this.enabled.set(instanceId, roots)
+    }
+    if (enabled) {
+      roots.add(root)
+    } else {
+      roots.delete(root)
+      if (roots.size === 0) {
+        this.enabled.delete(instanceId)
+      }
+    }
+  }
+
+  toggle(instanceId: string, sessionId: string): boolean {
+    const next = !this.isEnabled(instanceId, sessionId)
+    this.setEnabled(instanceId, sessionId, next)
+    return next
+  }
+
+  upsertSession(instanceId: string, info: AutoAcceptSessionInfo): void {
+    let tree = this.sessions.get(instanceId)
+    if (!tree) {
+      tree = new Map()
+      this.sessions.set(instanceId, tree)
+    }
+    tree.set(info.id, {
+      id: info.id,
+      parentId: info.parentId ?? null,
+      revert: info.revert,
+    })
+    this.migrateEnabledRoots(instanceId)
+  }
+
+  removeSession(instanceId: string, sessionId: string): void {
+    this.sessions.get(instanceId)?.delete(sessionId)
+  }
+
+  clearInstance(instanceId: string): void {
+    this.sessions.delete(instanceId)
+    this.enabled.delete(instanceId)
+  }
+
+  /** Resolves the family-root session id for the given session. */
+  familyRoot(instanceId: string, sessionId: string): string {
+    const tree = this.sessions.get(instanceId)
+    return resolveFamilyRoot(sessionId, (id) => tree?.get(id))
+  }
+
+  enabledRoots(instanceId: string): string[] {
+    return [...(this.enabled.get(instanceId) ?? [])]
+  }
+
+  /**
+   * Re-resolves every enabled family root for an instance after the session
+   * tree changes (new session, updated parent/revert). If a root now resolves
+   * to a different id, the enabled entry is migrated so toggles survive late
+   * ancestry discovery.
+   */
+  private migrateEnabledRoots(instanceId: string): void {
+    const roots = this.enabled.get(instanceId)
+    if (!roots || roots.size === 0) return
+    for (const oldRoot of Array.from(roots)) {
+      const newRoot = this.familyRoot(instanceId, oldRoot)
+      if (newRoot !== oldRoot) {
+        roots.delete(oldRoot)
+        roots.add(newRoot)
+      }
+    }
+  }
+}
diff --git a/packages/server/src/permissions/opencode-replier.ts b/packages/server/src/permissions/opencode-replier.ts
new file mode 100644
index 00000000..2ed9bfc9
--- /dev/null
+++ b/packages/server/src/permissions/opencode-replier.ts
@@ -0,0 +1,47 @@
+import type { WorkspaceManager } from "../workspaces/manager"
+import type { Logger } from "../logger"
+import { createInstanceClient } from "../workspaces/instance-client"
+import type { AutoAcceptReply, PermissionReplier } from "./auto-accept-manager"
+
+interface OpencodeReplierDeps {
+  workspaceManager: WorkspaceManager
+  logger: Logger
+}
+
+/**
+ * Default {@link PermissionReplier} that calls the OpenCode instance via the
+ * generated SDK client over loopback, using the same `"once"` reply the UI
+ * previously sent.
+ *
+ * Uses `createInstanceClient` so routes and body shapes are always correct
+ * for the installed SDK version — no hand-assembled URLs.
+ */
+export function createOpencodePermissionReplier(deps: OpencodeReplierDeps): PermissionReplier {
+  return async (reply: AutoAcceptReply) => {
+    const client = createInstanceClient(deps.workspaceManager, reply.instanceId)
+    if (!client) {
+      throw new Error(`Yolo: instance ${reply.instanceId} has no open port`)
+    }
+
+    const opts = { throwOnError: true } as const
+
+    if (reply.source === "v2") {
+      await client.v2.session.permission.reply(
+        {
+          sessionID: reply.sessionId,
+          requestID: reply.permissionId,
+          reply: reply.reply,
+        },
+        opts,
+      )
+    } else {
+      await client.permission.reply(
+        {
+          requestID: reply.permissionId,
+          reply: reply.reply,
+        },
+        opts,
+      )
+    }
+  }
+}
diff --git a/packages/server/src/permissions/opencode-yolo-metadata.test.ts b/packages/server/src/permissions/opencode-yolo-metadata.test.ts
new file mode 100644
index 00000000..d31d5652
--- /dev/null
+++ b/packages/server/src/permissions/opencode-yolo-metadata.test.ts
@@ -0,0 +1,61 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { createOpencodeYoloPersistence, hasPersistedYolo, mergePersistedYolo } from "./opencode-yolo-metadata"
+
+describe("OpenCode Yolo metadata", () => {
+  it("preserves unrelated metadata while replacing Yolo state", () => {
+    assert.deepEqual(
+      mergePersistedYolo({ thirdParty: { keep: true }, codenomad: { version: 1, worktreeSlug: "feature" } }, "root", true),
+      {
+        thirdParty: { keep: true },
+        codenomad: { version: 1, worktreeSlug: "feature", yolo: { enabled: true, rootSessionId: "root" } },
+      },
+    )
+  })
+
+  it("accepts only a marker owned by its session", () => {
+    const metadata = mergePersistedYolo({}, "root", true)
+    assert.equal(hasPersistedYolo("root", metadata), true)
+    assert.equal(hasPersistedYolo("fork", metadata), false)
+    assert.equal(hasPersistedYolo("root", mergePersistedYolo({}, "root", false)), false)
+  })
+
+  it("uses the session workspace for metadata updates", async () => {
+    const calls: Array<Record<string, unknown>> = []
+    const client = {
+      session: {
+        async list() { return { data: [{ id: "root", parentID: null, workspaceID: "workspace", metadata: {} }] } },
+        async get(parameters: Record<string, unknown>) { calls.push(parameters); return { data: { metadata: {} } } },
+        async update(parameters: Record<string, unknown>) { calls.push(parameters); return { data: {} } },
+      },
+    }
+    const persistence = createOpencodeYoloPersistence({} as never, () => client as never)
+    const [session] = await persistence.loadSessions("instance")
+    await persistence.persist("instance", "root", true, session?.workspaceId)
+    assert.equal(session?.workspaceId, "workspace")
+    assert.equal(calls[0]?.workspace, "workspace")
+    assert.equal(calls[1]?.workspace, "workspace")
+  })
+
+  it("serializes Yolo and worktree metadata writes across instances", async () => {
+    let metadata: Record<string, unknown> = { thirdParty: true }
+    const client = {
+      session: {
+        async get() { return { data: { metadata } } },
+        async update(parameters: Record<string, unknown>) {
+          metadata = parameters.metadata as Record<string, unknown>
+          return { data: { metadata } }
+        },
+      },
+    }
+    const persistence = createOpencodeYoloPersistence({} as never, () => client as never)
+    await Promise.all([
+      persistence.persist("instance-a", "root", true),
+      persistence.setWorktreeSlug("instance-b", "root", "feature"),
+    ])
+    assert.deepEqual(metadata, {
+      thirdParty: true,
+      codenomad: { version: 1, yolo: { enabled: true, rootSessionId: "root" }, worktreeSlug: "feature" },
+    })
+  })
+})
diff --git a/packages/server/src/permissions/opencode-yolo-metadata.ts b/packages/server/src/permissions/opencode-yolo-metadata.ts
new file mode 100644
index 00000000..bca92901
--- /dev/null
+++ b/packages/server/src/permissions/opencode-yolo-metadata.ts
@@ -0,0 +1,111 @@
+import type { OpencodeClient } from "@opencode-ai/sdk/v2/client"
+import type { WorkspaceManager } from "../workspaces/manager"
+import { createInstanceClient } from "../workspaces/instance-client"
+import type { AutoAcceptPersistence, PersistedAutoAcceptSession } from "./auto-accept-manager"
+
+const CODENOMAD_METADATA_VERSION = 1
+const SESSION_LIST_LIMIT = 10_000
+
+type Metadata = Record<string, unknown>
+
+export interface OpencodeYoloPersistence extends AutoAcceptPersistence {
+  hasProjectSession(instanceId: string, sessionId: string): Promise<boolean>
+  setWorktreeSlug(instanceId: string, sessionId: string, worktreeSlug: string): Promise<Metadata>
+}
+
+function record(value: unknown): Metadata {
+  return value && typeof value === "object" && !Array.isArray(value) ? { ...(value as Metadata) } : {}
+}
+
+export function hasPersistedYolo(sessionId: string, metadata: unknown): boolean {
+  const codenomad = record(record(metadata).codenomad)
+  const yolo = record(codenomad.yolo)
+  return codenomad.version === CODENOMAD_METADATA_VERSION
+    && yolo.enabled === true
+    && yolo.rootSessionId === sessionId
+}
+
+export function mergePersistedYolo(metadata: unknown, rootSessionId: string, enabled: boolean): Metadata {
+  const current = record(metadata)
+  const codenomad = record(current.codenomad)
+  return {
+    ...current,
+    codenomad: {
+      ...codenomad,
+      version: CODENOMAD_METADATA_VERSION,
+      yolo: { enabled, rootSessionId },
+    },
+  }
+}
+
+export function mergePersistedWorktreeSlug(metadata: unknown, worktreeSlug: string): Metadata {
+  const current = record(metadata)
+  const codenomad = record(current.codenomad)
+  return {
+    ...current,
+    codenomad: { ...codenomad, version: CODENOMAD_METADATA_VERSION, worktreeSlug },
+  }
+}
+
+export function createOpencodeYoloPersistence(
+  workspaceManager: WorkspaceManager,
+  createClient: (manager: WorkspaceManager, instanceId: string) => OpencodeClient | null = createInstanceClient,
+): OpencodeYoloPersistence {
+  const writes = new Map<string, Promise<unknown>>()
+  const clientFor = (instanceId: string) => {
+    const client = createClient(workspaceManager, instanceId)
+    if (!client) throw new Error(`Yolo: instance ${instanceId} has no open port`)
+    return client
+  }
+  const updateMetadata = (
+    instanceId: string,
+    sessionId: string,
+    workspaceId: string | undefined,
+    update: (metadata: unknown) => Metadata,
+  ): Promise<Metadata> => {
+    const writeKey = sessionId
+    const write = (writes.get(writeKey) ?? Promise.resolve()).catch(() => undefined).then(async () => {
+      const client = clientFor(instanceId)
+      const scope = { sessionID: sessionId, ...(workspaceId ? { workspace: workspaceId } : {}) }
+      const { data: session } = await client.session.get(scope, { throwOnError: true })
+      const metadata = update(session.metadata)
+      const { data } = await client.session.update({ ...scope, metadata }, { throwOnError: true })
+      return record(data?.metadata ?? metadata)
+    })
+    const settled = write.finally(() => {
+      if (writes.get(writeKey) === settled) writes.delete(writeKey)
+    })
+    writes.set(writeKey, settled)
+    return settled
+  }
+  return {
+    async loadSessions(instanceId): Promise<PersistedAutoAcceptSession[]> {
+      const { data } = await clientFor(instanceId).session.list(
+        { scope: "project", limit: SESSION_LIST_LIMIT },
+        { throwOnError: true },
+      )
+      return (data ?? []).map((session) => ({
+        id: session.id,
+        parentId: session.parentID ?? null,
+        revert: session.revert,
+        workspaceId: session.workspaceID,
+        yoloEnabled: hasPersistedYolo(session.id, session.metadata),
+      }))
+    },
+    persist(instanceId, rootSessionId, enabled, workspaceId): Promise<void> {
+      return updateMetadata(instanceId, rootSessionId, workspaceId,
+        (metadata) => mergePersistedYolo(metadata, rootSessionId, enabled)).then(() => undefined)
+    },
+    async hasProjectSession(instanceId, sessionId): Promise<boolean> {
+      const { data } = await clientFor(instanceId).session.list(
+        { scope: "project", limit: SESSION_LIST_LIMIT },
+        { throwOnError: true },
+      )
+      return (data ?? []).some((session) => session.id === sessionId)
+    },
+    setWorktreeSlug(instanceId, sessionId, worktreeSlug): Promise<Metadata> {
+      return updateMetadata(instanceId, sessionId, undefined,
+        (metadata) => mergePersistedWorktreeSlug(metadata, worktreeSlug))
+    },
+  }
+}
diff --git a/packages/server/src/server/__tests__/remote-proxy.test.ts b/packages/server/src/server/__tests__/remote-proxy.test.ts
index 5daac01a..f4e5053d 100644
--- a/packages/server/src/server/__tests__/remote-proxy.test.ts
+++ b/packages/server/src/server/__tests__/remote-proxy.test.ts
@@ -13,32 +13,20 @@ import { RemoteProxySessionManager } from "../remote-proxy"
 import { resolveHttpsOptions } from "../tls"
 
 const sharedTempDir = fs.mkdtempSync(path.join(os.tmpdir(), "codenomad-remote-proxy-test-"))
-const sharedTls = resolveHttpsOptions({
-  enabled: true,
-  configDir: sharedTempDir,
-  host: "127.0.0.1",
-  logger: createStubLogger(),
-})
-
-if (!sharedTls) {
-  throw new Error("Failed to generate HTTPS options for remote proxy tests")
-}
-
+const sharedTls = resolveHttpsOptions({ enabled: true, configDir: sharedTempDir, host: "127.0.0.1", logger: createStubLogger() })
+if (!sharedTls) throw new Error("Failed to generate HTTPS options for remote proxy tests")
 const sharedHttpsOptions = sharedTls.httpsOptions
-
 const httpsDispatcher = new Agent({ connect: { rejectUnauthorized: false } })
 const managers = new Set<RemoteProxySessionManager>()
 
 afterEach(async () => {
-  for (const manager of managers) {
-    await disposeManager(manager)
-  }
+  for (const manager of managers) await manager.shutdown().catch(() => undefined)
   managers.clear()
 })
 
-after(() => {
+after(async () => {
   fs.rmSync(sharedTempDir, { recursive: true, force: true })
-  httpsDispatcher.close().catch(() => {})
+  await httpsDispatcher.destroy().catch(() => {})
 })
 
 describe("RemoteProxySessionManager", () => {
@@ -47,10 +35,8 @@ describe("RemoteProxySessionManager", () => {
       const manager = createSessionManager()
       const session1 = await createSession(manager, `${upstreamBaseUrl}/base`)
       const session2 = await createSession(manager, `${upstreamBaseUrl}/base`)
-
       const blocked = await proxyFetch(`${session1.proxyOrigin}/status`)
       assert.equal(blocked.status, 403)
-
       const wrongTokenResponse = await proxyFetch(`${session1.proxyOrigin}/__codenomad/api/auth/token`, {
         method: "POST",
         headers: { "content-type": "application/json" },
@@ -70,9 +56,7 @@ describe("RemoteProxySessionManager", () => {
     await withUpstreamServer(async (upstreamBaseUrl) => {
       const manager = createSessionManager()
       const session = await createSession(manager, `${upstreamBaseUrl}/base`)
-
       await activateSession(session)
-
       const apiResponse = await proxyFetch(`${session.proxyOrigin}/api/auth/status?foo=bar`)
       assert.equal(apiResponse.status, 200)
       assert.equal(await apiResponse.text(), "/base/api/auth/status?foo=bar")
@@ -84,10 +68,8 @@ describe("RemoteProxySessionManager", () => {
       const requestUrl = req.url ?? ""
       if (requestUrl === "/base/redirect") {
         res.writeHead(302, { location: "/base/after?ok=1" })
-        res.end()
-        return
+        return res.end()
       }
-
       res.writeHead(200, { "content-type": "text/plain" })
       res.end(requestUrl)
     })
@@ -97,21 +79,17 @@ describe("RemoteProxySessionManager", () => {
     await withUpstreamServer(async (upstreamBaseUrl) => {
       const manager = createSessionManager()
       const session = await createSession(manager, `${upstreamBaseUrl}/base`)
-
       await activateSession(session)
-
       const loginResponse = await proxyFetch(`${session.proxyOrigin}/login`)
       assert.equal(loginResponse.status, 200)
       const setCookie = getSetCookie(loginResponse)[0]
 
       assert.match(setCookie, /^cnrp_[0-9a-f]+_session=abc123/i)
       assert.doesNotMatch(setCookie, /domain=/i)
-
       const cookieHeader = setCookie.split(";", 1)[0]
       const whoamiResponse = await proxyFetch(`${session.proxyOrigin}/whoami`, {
         headers: { cookie: cookieHeader },
       })
-
       assert.equal(await whoamiResponse.text(), "session=abc123")
     }, (req, res) => {
       const requestUrl = req.url ?? ""
@@ -120,16 +98,12 @@ describe("RemoteProxySessionManager", () => {
           "content-type": "text/plain",
           "set-cookie": "session=abc123; Path=/; Secure; HttpOnly; Domain=127.0.0.1",
         })
-        res.end("ok")
-        return
+        return res.end("ok")
       }
-
       if (requestUrl === "/base/whoami") {
         res.writeHead(200, { "content-type": "text/plain" })
-        res.end(req.headers.cookie ?? "")
-        return
+        return res.end(req.headers.cookie ?? "")
       }
-
       res.writeHead(404, { "content-type": "text/plain" })
       res.end(requestUrl)
     })
@@ -139,17 +113,13 @@ describe("RemoteProxySessionManager", () => {
     await withUpstreamServer(async (upstreamBaseUrl) => {
       const manager = createSessionManager()
       const session = await createSession(manager, `${upstreamBaseUrl}/base`)
-
       assert.equal(await manager.deleteSession(session.sessionId), true)
       assert.equal(await manager.deleteSession(session.sessionId), false)
-
       const session3 = await createSession(manager, `${upstreamBaseUrl}/base`)
       const internalSessions = (manager as any).sessions as Map<string, { lastAccessAt: number }>
       const internalCleanup = (manager as any).cleanupExpiredSessions as () => Promise<void>
-
       internalSessions.get(session3.sessionId)!.lastAccessAt = Date.now() - 31 * 60_000
       await internalCleanup.call(manager)
-
       assert.equal(internalSessions.has(session3.sessionId), false)
       assert.equal(await manager.deleteSession(session3.sessionId), false)
     }, (_req, res) => {
@@ -157,20 +127,153 @@ describe("RemoteProxySessionManager", () => {
       res.end("ok")
     })
   })
+
+  it("closes every session listener during shutdown", async () => {
+    await withUpstreamServer(async (upstreamBaseUrl) => {
+      const manager = createSessionManager()
+      const first = await createSession(manager, `${upstreamBaseUrl}/base`)
+      await createSession(manager, `${upstreamBaseUrl}/other`)
+      await manager.shutdown()
+      assert.equal((manager as any).sessions.size, 0)
+      await assert.rejects(proxyFetch(`${first.proxyOrigin}/status`))
+    }, (_req, res) => {
+      res.writeHead(200).end("ok")
+    })
+  })
+
+  it("waits for in-flight idle cleanup during shutdown", async () => {
+    await withUpstreamServer(async (upstreamBaseUrl) => {
+      const manager = createSessionManager({ disposalTimeoutMs: 1_000 })
+      const session = await createSession(manager, `${upstreamBaseUrl}/base`)
+      const internalSession = (manager as any).sessions.get(session.sessionId)
+      const closeGate = deferred<void>()
+      const originalClose = internalSession.app.close.bind(internalSession.app)
+      internalSession.app.close = async () => {
+        await closeGate.promise
+        return originalClose()
+      }
+      internalSession.lastAccessAt = Date.now() - 31 * 60_000
+      const cleanup = (manager as any).cleanupExpiredSessions() as Promise<void>
+      let shutdownSettled = false
+      const shutdown = manager.shutdown().then(() => {
+        shutdownSettled = true
+      })
+      await new Promise((resolve) => setImmediate(resolve))
+      assert.equal(shutdownSettled, false)
+      closeGate.resolve()
+      await cleanup
+      await shutdown
+      assert.equal((manager as any).disposals.size, 0)
+    }, (_req, res) => {
+      res.writeHead(200).end("ok")
+    })
+  })
+
+  it("aborts a stalled event stream during bounded shutdown", async () => {
+    await withUpstreamServer(async (upstreamBaseUrl) => {
+      const manager = createSessionManager({ disposalTimeoutMs: 100 })
+      const session = await createSession(manager, `${upstreamBaseUrl}/base`)
+      await activateSession(session)
+      const response = await proxyFetch(`${session.proxyOrigin}/events`)
+      assert.equal(response.status, 200)
+      await Promise.race([
+        manager.shutdown(),
+        new Promise<never>((_resolve, reject) => setTimeout(() => reject(new Error("shutdown stalled")), 500)),
+      ])
+      assert.equal((manager as any).sessions.size, 0)
+      assert.equal((manager as any).disposals.size, 0)
+    }, (req, res) => {
+      if (req.url === "/base/events") {
+        res.writeHead(200, { "content-type": "text/event-stream" })
+        return void res.write("data: connected\n\n")
+      }
+      res.writeHead(200).end("ok")
+    })
+  })
+
+  it("surfaces listener disposal failures", async () => {
+    await withUpstreamServer(async (upstreamBaseUrl) => {
+      const manager = createSessionManager()
+      const session = await createSession(manager, `${upstreamBaseUrl}/base`)
+      const internalSession = (manager as any).sessions.get(session.sessionId)
+      const originalClose = internalSession.app.close.bind(internalSession.app)
+      let failClose = true
+      internalSession.app.close = async () => {
+        await originalClose()
+        if (failClose) { failClose = false; throw new Error("close failed") }
+      }
+      await assert.rejects(manager.deleteSession(session.sessionId), /Remote proxy disposal failed/)
+      // A completed deletion failure predating shutdown must not poison it.
+      await manager.shutdown()
+      assert.equal((manager as any).sessions.size, 0)
+    }, (_req, res) => {
+      res.writeHead(200).end("ok")
+    })
+  })
+
+  it("waits for in-flight creation and rejects sessions that cross shutdown", async () => {
+    await withUpstreamServer(async (upstreamBaseUrl) => {
+      const manager = createSessionManager()
+      const creation = manager.createSession(`${upstreamBaseUrl}/base`, false)
+      const shutdown = manager.shutdown()
+      await assert.rejects(creation, /shutting down/)
+      await shutdown
+      assert.equal((manager as any).creations.size, 0)
+      assert.equal((manager as any).sessions.size, 0)
+      await assert.rejects(manager.createSession(`${upstreamBaseUrl}/base`, false), /shutting down/)
+    }, (_req, res) => {
+      res.writeHead(200).end("ok")
+    })
+  })
+
+  it("coalesces shutdown, retains current disposal failures, and gives every session its own agent", async () => {
+    await withUpstreamServer(async (upstreamBaseUrl) => {
+      const manager = createSessionManager()
+      const verified = await manager.createSession(`${upstreamBaseUrl}/verified`, false)
+      const insecure = await manager.createSession(`${upstreamBaseUrl}/insecure`, true)
+      const sessions = (manager as any).sessions as Map<string, any>
+      assert.ok(sessions.get(verified.sessionId).dispatcher instanceof Agent)
+      assert.ok(sessions.get(insecure.sessionId).dispatcher instanceof Agent)
+      assert.notStrictEqual(sessions.get(verified.sessionId).dispatcher, sessions.get(insecure.sessionId).dispatcher)
+
+      const closeGate = deferred<void>()
+      const originalClose = sessions.get(verified.sessionId).app.close.bind(sessions.get(verified.sessionId).app)
+      let failClose = true
+      sessions.get(verified.sessionId).app.close = async () => {
+        await closeGate.promise
+        await originalClose()
+        if (failClose) { failClose = false; throw new Error("current close failed") }
+      }
+      const disposal = manager.deleteSession(verified.sessionId); const first = manager.shutdown()
+      const concurrent = manager.shutdown()
+      assert.strictEqual(first, concurrent)
+      closeGate.resolve()
+      await assert.rejects(disposal, /Remote proxy disposal failed/)
+      await assert.rejects(first, (error: unknown) => error instanceof AggregateError && error.errors.some((cause) =>
+        cause instanceof AggregateError && cause.errors.some((nested) => /current close failed/.test(String(nested)))))
+      await manager.shutdown()
+      assert.equal(sessions.size, 0)
+    }, (_req, res) => {
+      res.writeHead(200).end("ok")
+    })
+  })
 })
 
-function createSessionManager() {
+function createSessionManager(options: { disposalTimeoutMs?: number } = {}) {
   const manager = new RemoteProxySessionManager({
-    authManager: {
-      isLoopbackRequest: () => true,
-    } as unknown as AuthManager,
-    logger: createStubLogger(),
-    httpsOptions: sharedHttpsOptions,
+    authManager: { isLoopbackRequest: () => true } as unknown as AuthManager,
+    logger: createStubLogger(), httpsOptions: sharedHttpsOptions, ...options,
   })
   managers.add(manager)
   return manager
 }
 
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((resolvePromise) => { resolve = resolvePromise })
+  return { promise, resolve }
+}
+
 async function createSession(manager: RemoteProxySessionManager, baseUrl: string) {
   const created = await manager.createSession(baseUrl, false)
   const windowUrl = new URL(created.windowUrl)
@@ -188,18 +291,14 @@ async function activateSession(session: { proxyOrigin: string; token: string })
     headers: { "content-type": "application/json" },
     body: JSON.stringify({ token: session.token }),
   })
-  if (!response.ok) {
-    return false
-  }
+  if (!response.ok) return false
   const body = (await response.json()) as { ok?: boolean }
   return body.ok === true
 }
 
 function getSetCookie(response: Awaited<ReturnType<typeof fetch>>): string[] {
   const values = (response.headers as any).getSetCookie?.() as string[] | undefined
-  if (Array.isArray(values) && values.length > 0) {
-    return values
-  }
+  if (Array.isArray(values) && values.length > 0) return values
   const fallback = response.headers.get("set-cookie")
   return fallback ? [fallback] : []
 }
@@ -208,26 +307,15 @@ async function proxyFetch(url: string, init?: Parameters<typeof fetch>[1]) {
   return fetch(url, { dispatcher: httpsDispatcher, ...init })
 }
 
-async function disposeManager(manager: RemoteProxySessionManager) {
-  const sessions = Array.from(((manager as any).sessions as Map<string, unknown>).keys())
-  for (const sessionId of sessions) {
-    await manager.deleteSession(sessionId)
-  }
-  clearInterval((manager as any).cleanupTimer as NodeJS.Timeout)
-}
-
 async function withUpstreamServer(
   callback: (baseUrl: string) => Promise<void>,
   handler: (req: IncomingMessage, res: ServerResponse<IncomingMessage>) => void,
 ) {
   const server = http.createServer(handler)
   await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", () => resolve()))
-
   try {
     const address = server.address()
-    if (!address || typeof address === "string") {
-      throw new Error("Failed to resolve upstream server address")
-    }
+    if (!address || typeof address === "string") throw new Error("Failed to resolve upstream server address")
     await callback(`http://127.0.0.1:${address.port}`)
   } finally {
     await new Promise<void>((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))
@@ -235,14 +323,6 @@ async function withUpstreamServer(
 }
 
 function createStubLogger(): Logger {
-  const logger = {
-    info() {},
-    warn() {},
-    error() {},
-    child() {
-      return logger
-    },
-  }
-
+  const logger = { info() {}, warn() {}, error() {}, child() { return logger } }
   return logger as unknown as Logger
 }
diff --git a/packages/server/src/server/http-server.ts b/packages/server/src/server/http-server.ts
index 5dd85468..8df2832b 100644
--- a/packages/server/src/server/http-server.ts
+++ b/packages/server/src/server/http-server.ts
@@ -22,15 +22,20 @@ import { registerEventRoutes } from "./routes/events"
 import { registerStorageRoutes } from "./routes/storage"
 import { registerPluginRoutes } from "./routes/plugin"
 import { registerBackgroundProcessRoutes } from "./routes/background-processes"
+import { registerYoloRoutes } from "./routes/yolo"
 import { registerWorktreeRoutes } from "./routes/worktrees"
 import { registerSpeechRoutes } from "./routes/speech"
+import { registerOpenCodeUpdateRoutes } from "./routes/opencode-update"
 import { registerRemoteServerRoutes } from "./routes/remote-servers"
 import { registerRemoteProxyRoutes } from "./routes/remote-proxy"
 import { registerSideCarRoutes } from "./routes/sidecars"
 import { registerPreviewRoutes } from "./routes/previews"
+import { registerUsageRoutes } from "./routes/usage"
 import { ServerMeta } from "../api-types"
 import { InstanceStore } from "../storage/instance-store"
 import { BackgroundProcessManager } from "../background-processes/manager"
+import type { AutoAcceptManager } from "../permissions/auto-accept-manager"
+import type { OpencodeYoloPersistence } from "../permissions/opencode-yolo-metadata"
 import type { AuthManager } from "../auth/manager"
 import { registerAuthRoutes } from "./routes/auth"
 import { sendUnauthorized, wantsHtml } from "../auth/http-auth"
@@ -41,6 +46,7 @@ import { VoiceModeManager } from "../plugins/voice-mode"
 import type { SideCarManager } from "../sidecars/manager"
 import type { PreviewManager } from "../previews/manager"
 import type { RemoteProxySessionManager } from "./remote-proxy"
+import { createOpenCodeUpdateService } from "../opencode-update/service"
 
 interface HttpServerDeps {
   bindHost: string
@@ -63,6 +69,8 @@ interface HttpServerDeps {
   pluginChannel: PluginChannelManager
   voiceModeManager: VoiceModeManager
   remoteProxySessionManager: RemoteProxySessionManager
+  yoloManager: AutoAcceptManager
+  sessionMetadataPersistence: OpencodeYoloPersistence
   uiStaticDir: string
   uiDevServerUrl?: string
   logger: Logger
@@ -269,6 +277,10 @@ export function createHttpServer(deps: HttpServerDeps) {
 
   registerWorkspaceRoutes(app, { workspaceManager: deps.workspaceManager })
   registerSettingsRoutes(app, { settings: deps.settings, logger: apiLogger })
+  registerOpenCodeUpdateRoutes(app, {
+    service: createOpenCodeUpdateService(deps.settings, deps.workspaceManager),
+    logger: apiLogger,
+  })
   registerFilesystemRoutes(app, { fileSystemBrowser: deps.fileSystemBrowser })
   registerConfigFileRoutes(app)
   registerMetaRoutes(app, { serverMeta: deps.serverMeta })
@@ -278,7 +290,10 @@ export function createHttpServer(deps: HttpServerDeps) {
     logger: sseLogger,
     connectionManager: deps.clientConnectionManager,
   })
-  registerWorktreeRoutes(app, { workspaceManager: deps.workspaceManager })
+  registerWorktreeRoutes(app, {
+    workspaceManager: deps.workspaceManager,
+    sessionMetadataPersistence: deps.sessionMetadataPersistence,
+  })
   registerStorageRoutes(app, {
     instanceStore: deps.instanceStore,
     eventBus: deps.eventBus,
@@ -289,6 +304,7 @@ export function createHttpServer(deps: HttpServerDeps) {
   registerSpeechRoutes(app, { speechService: deps.speechService })
   registerSideCarRoutes(app, { sidecarManager: deps.sidecarManager })
   registerPreviewRoutes(app, { previewManager: deps.previewManager })
+  registerUsageRoutes(app)
   registerSideCarProxyRoutes(app, { sidecarManager: deps.sidecarManager, logger: proxyLogger })
   registerPreviewProxyRoutes(app, { previewManager: deps.previewManager, logger: proxyLogger })
   setupSideCarWebSocketProxy(app, {
@@ -309,6 +325,7 @@ export function createHttpServer(deps: HttpServerDeps) {
     voiceModeManager: deps.voiceModeManager,
   })
   registerBackgroundProcessRoutes(app, { backgroundProcessManager })
+  registerYoloRoutes(app, { yoloManager: deps.yoloManager })
   registerInstanceProxyRoutes(app, { workspaceManager: deps.workspaceManager, logger: proxyLogger })
 
 
diff --git a/packages/server/src/server/remote-proxy.ts b/packages/server/src/server/remote-proxy.ts
index 93e6ab5e..a4c47aac 100644
--- a/packages/server/src/server/remote-proxy.ts
+++ b/packages/server/src/server/remote-proxy.ts
@@ -10,20 +10,18 @@ const LOOPBACK_HOST = "127.0.0.1"
 const BOOTSTRAP_PAGE_PATH = "/__codenomad/auth/token"
 const BOOTSTRAP_EXCHANGE_PATH = "/__codenomad/api/auth/token"
 const SESSION_IDLE_TTL_MS = 30 * 60_000
+const SESSION_DISPOSAL_TIMEOUT_MS = 5_000
 
 interface RemoteProxySession {
   id: string
   bootstrapToken: string
   targetBaseUrl: URL
-  skipTlsVerify: boolean
   localBaseUrl: URL
-  entryUrl: URL
-  bootstrapUrl: string
   activated: boolean
   cookiePrefix: string
   app: FastifyInstance
   dispatcher?: Agent
-  createdAt: number
+  abortController: AbortController
   lastAccessAt: number
 }
 
@@ -31,6 +29,7 @@ export interface RemoteProxySessionManagerOptions {
   authManager: AuthManager
   logger: Logger
   httpsOptions?: { key: string | Buffer; cert: string | Buffer; ca?: string | Buffer }
+  disposalTimeoutMs?: number
 }
 
 export interface RemoteProxySessionCreateResult {
@@ -40,16 +39,26 @@ export interface RemoteProxySessionCreateResult {
 
 export class RemoteProxySessionManager {
   private readonly sessions = new Map<string, RemoteProxySession>()
+  private readonly creations = new Set<Promise<unknown>>()
+  private readonly disposals = new Set<Promise<unknown>>()
+  private readonly sessionDisposals = new Map<string, Promise<boolean>>()
   private readonly cleanupTimer: NodeJS.Timeout
+  private shuttingDown = false
+  private shutdownPromise?: Promise<void>
 
   constructor(private readonly options: RemoteProxySessionManagerOptions) {
-    this.cleanupTimer = setInterval(() => {
-      void this.cleanupExpiredSessions()
-    }, 60_000)
+    this.cleanupTimer = setInterval(() => void this.cleanupExpiredSessions().catch((error) =>
+      this.options.logger.error({ err: error }, "Failed to dispose expired remote proxy session")), 60_000)
     this.cleanupTimer.unref()
   }
 
   async createSession(baseUrl: string, skipTlsVerify: boolean): Promise<RemoteProxySessionCreateResult> {
+    if (this.shuttingDown) throw new Error("Remote proxy session manager is shutting down")
+
+    return this.track(this.creations, this.createSessionInternal(baseUrl, skipTlsVerify))
+  }
+
+  private async createSessionInternal(baseUrl: string, skipTlsVerify: boolean): Promise<RemoteProxySessionCreateResult> {
     if (!this.options.httpsOptions) {
       throw new Error("Local HTTPS is required for remote proxy sessions")
     }
@@ -57,8 +66,9 @@ export class RemoteProxySessionManager {
     const targetBaseUrl = normalizeBaseUrl(baseUrl)
     const sessionId = randomUUID()
     const bootstrapToken = randomBytes(32).toString("base64url")
-    const dispatcher = skipTlsVerify ? new Agent({ connect: { rejectUnauthorized: false } }) : undefined
-    const app = Fastify({ logger: false, https: this.options.httpsOptions })
+    const dispatcher = new Agent(skipTlsVerify ? { connect: { rejectUnauthorized: false } } : {})
+    const abortController = new AbortController()
+    const app = Fastify({ logger: false, https: this.options.httpsOptions, forceCloseConnections: true })
     let session: RemoteProxySession | null = null
 
     app.removeAllContentTypeParsers()
@@ -99,7 +109,7 @@ export class RemoteProxySessionManager {
       reply.send({ ok: true })
     })
 
-    app.all("/*", async (request, reply) => {
+    const handleProxyRequest = async (request: FastifyRequest, reply: FastifyReply) => {
       if (!session) {
         reply.code(503).send({ error: "Remote proxy session is unavailable" })
         return
@@ -112,58 +122,72 @@ export class RemoteProxySessionManager {
 
       session.lastAccessAt = Date.now()
       await proxyRequest({ request, reply, session, logger: this.options.logger })
-    })
-
-    app.setNotFoundHandler(async (request, reply) => {
-      if (!session) {
-        reply.code(503).send({ error: "Remote proxy session is unavailable" })
-        return
-      }
-
-      if (!session.activated) {
-        reply.code(403).send({ error: "Remote proxy session is not activated" })
-        return
-      }
-
-      session.lastAccessAt = Date.now()
-      await proxyRequest({ request, reply, session, logger: this.options.logger })
-    })
+    }
+    app.all("/*", handleProxyRequest)
+    app.setNotFoundHandler(handleProxyRequest)
 
     const addressInfo = await app.listen({ host: LOOPBACK_HOST, port: 0 })
     const address = new URL(addressInfo)
     const localBaseUrl = new URL(`https://${LOOPBACK_HOST}:${address.port}`)
     const entryUrl = new URL(targetBaseUrl.pathname || "/", localBaseUrl)
     const returnTo = buildReturnToTarget(entryUrl)
+    const bootstrapUrl = `${localBaseUrl.origin}${BOOTSTRAP_PAGE_PATH}?returnTo=${encodeURIComponent(returnTo)}#${encodeURIComponent(bootstrapToken)}`
 
     session = {
       id: sessionId,
       bootstrapToken,
       targetBaseUrl,
-      skipTlsVerify,
       localBaseUrl,
-      entryUrl,
-      bootstrapUrl: `${localBaseUrl.origin}${BOOTSTRAP_PAGE_PATH}?returnTo=${encodeURIComponent(returnTo)}#${encodeURIComponent(bootstrapToken)}`,
       activated: false,
       cookiePrefix: `cnrp_${randomBytes(6).toString("hex")}_`,
       app,
       dispatcher,
-      createdAt: Date.now(),
+      abortController,
       lastAccessAt: Date.now(),
     }
 
     this.sessions.set(sessionId, session)
+    if (this.shuttingDown) {
+      await this.disposeSession(sessionId)
+      throw new Error("Remote proxy session manager is shutting down")
+    }
     this.options.logger.info(
       { sessionId, targetBaseUrl: targetBaseUrl.toString(), localBaseUrl: localBaseUrl.toString() },
       "Created remote proxy session",
     )
 
-    return { sessionId, windowUrl: session.bootstrapUrl }
+    return { sessionId, windowUrl: bootstrapUrl }
   }
 
   async deleteSession(sessionId: string): Promise<boolean> {
     return this.disposeSession(sessionId)
   }
 
+  shutdown(): Promise<void> {
+    if (this.shutdownPromise) return this.shutdownPromise
+    this.shuttingDown = true
+    clearInterval(this.cleanupTimer)
+    const shutdown = this.drainShutdown()
+    this.shutdownPromise = shutdown
+    void shutdown.finally(() => {
+      if (this.shutdownPromise === shutdown) this.shutdownPromise = undefined
+    }).catch(() => undefined)
+    return shutdown
+  }
+
+  private async drainShutdown(): Promise<void> {
+    const disposals = new Set(this.disposals)
+    while (this.creations.size > 0) {
+      await Promise.allSettled([...this.creations])
+      for (const disposal of this.disposals) disposals.add(disposal)
+    }
+    const pendingResults = await Promise.allSettled(disposals)
+    const results = await Promise.allSettled(Array.from(this.sessions.keys(), (id) => this.disposeSession(id)))
+    const failures = [...pendingResults, ...results]
+      .flatMap((result) => result.status === "rejected" ? [result.reason] : [])
+    if (failures.length) throw new AggregateError(failures, "Remote proxy shutdown failed")
+  }
+
   private async cleanupExpiredSessions() {
     const now = Date.now()
     for (const session of Array.from(this.sessions.values())) {
@@ -174,17 +198,47 @@ export class RemoteProxySessionManager {
     }
   }
 
-  private async disposeSession(sessionId: string): Promise<boolean> {
+  private disposeSession(sessionId: string): Promise<boolean> {
+    const pending = this.sessionDisposals.get(sessionId)
+    if (pending) return pending
     const session = this.sessions.get(sessionId)
-    if (!session) {
-      return false
-    }
+    if (!session) return Promise.resolve(false)
 
-    this.sessions.delete(sessionId)
-    session.dispatcher?.close().catch(() => {})
-    await session.app.close().catch(() => {})
-    this.options.logger.info({ sessionId }, "Disposed remote proxy session")
-    return true
+    session.abortController.abort()
+    const disposal = this.trackDisposal(this.disposeResources(session.app, session.dispatcher).then(() => {
+      if (this.sessions.get(sessionId) === session) this.sessions.delete(sessionId)
+      this.options.logger.info({ sessionId }, "Disposed remote proxy session")
+      return true
+    }))
+    this.sessionDisposals.set(sessionId, disposal)
+    void disposal.finally(() => {
+      if (this.sessionDisposals.get(sessionId) === disposal) this.sessionDisposals.delete(sessionId)
+    }).catch(() => undefined)
+    return disposal
+  }
+
+  private async disposeResources(app: FastifyInstance, dispatcher?: Agent): Promise<void> {
+    app.server.closeAllConnections?.()
+    const results = await Promise.race([
+      Promise.allSettled([app.close(), dispatcher?.destroy()]),
+      new Promise<never>((_resolve, reject) => AbortSignal.timeout(
+        Math.max(1, this.options.disposalTimeoutMs ?? SESSION_DISPOSAL_TIMEOUT_MS),
+      ).addEventListener(
+        "abort", () => reject(new Error("Remote proxy disposal timed out")),
+      )),
+    ])
+    const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : [])
+    if (failures.length) throw new AggregateError(failures, "Remote proxy disposal failed")
+  }
+
+  private track<T>(operations: Set<Promise<unknown>>, operation: Promise<T>): Promise<T> {
+    operations.add(operation)
+    void operation.finally(() => operations.delete(operation)).catch(() => undefined)
+    return operation
+  }
+
+  private trackDisposal<T>(operation: Promise<T>): Promise<T> {
+    return this.track(this.disposals, operation)
   }
 }
 
@@ -325,6 +379,7 @@ async function proxyRequest(args: {
     method: request.method,
     headers,
     dispatcher: session.dispatcher,
+    signal: session.abortController.signal,
     redirect: "manual",
   }
 
diff --git a/packages/server/src/server/routes/auth-pages/login.html b/packages/server/src/server/routes/auth-pages/login.html
index 5dea9c70..6aab2083 100644
--- a/packages/server/src/server/routes/auth-pages/login.html
+++ b/packages/server/src/server/routes/auth-pages/login.html
@@ -72,10 +72,10 @@
       <p>This CodeNomad server is protected. Enter your credentials to continue.</p>
 
       <label for="username">Username</label>
-      <input id="username" autocomplete="username" placeholder="{{DEFAULT_USERNAME}}" value="" />
+      <input id="username" autocomplete="username" autocapitalize="none" autocorrect="off" spellcheck="false" placeholder="{{DEFAULT_USERNAME}}" value="{{DEFAULT_USERNAME}}" />
 
       <label for="password">Password</label>
-      <input id="password" type="password" autocomplete="current-password" value="" />
+      <input id="password" type="password" autocomplete="current-password" autocapitalize="none" autocorrect="off" spellcheck="false" value="" />
 
       <button id="submit" type="button">Continue</button>
       <div id="error" class="error" style="display: none"></div>
@@ -95,7 +95,7 @@
 
       async function submit() {
         hideError()
-        const username = $("username").value.trim()
+        const username = $("username").value
         const password = $("password").value
         if (!username || !password) {
           showError("Username and password are required.")
diff --git a/packages/server/src/server/routes/auth.test.ts b/packages/server/src/server/routes/auth.test.ts
new file mode 100644
index 00000000..6d444a09
--- /dev/null
+++ b/packages/server/src/server/routes/auth.test.ts
@@ -0,0 +1,25 @@
+import assert from "node:assert/strict"
+import { it } from "node:test"
+import Fastify from "fastify"
+import type { AuthManager } from "../../auth/manager"
+import { registerAuthRoutes } from "./auth"
+
+it("renders the escaped default username literally as the login field value", async () => {
+  const app = Fastify({ logger: false })
+  const username = " code$&\"nomad "
+  const authManager = {
+    getSessionFromRequest: () => null,
+    getStatus: () => ({ username }),
+  } as unknown as AuthManager
+  registerAuthRoutes(app, { authManager })
+
+  const response = await app.inject({ method: "GET", url: "/login" })
+
+  assert.equal(response.statusCode, 200)
+  assert.ok(response.body.includes('value=" code$&amp;&quot;nomad "'))
+  assert.match(response.body, /const username = \$\("username"\)\.value\s*\n/)
+  assert.equal(response.body.match(/autocapitalize="none"/g)?.length, 2)
+  assert.equal(response.body.match(/autocorrect="off"/g)?.length, 2)
+  assert.equal(response.body.match(/spellcheck="false"/g)?.length, 2)
+  await app.close()
+})
diff --git a/packages/server/src/server/routes/auth.ts b/packages/server/src/server/routes/auth.ts
index 6bb7d3d3..a346124a 100644
--- a/packages/server/src/server/routes/auth.ts
+++ b/packages/server/src/server/routes/auth.ts
@@ -39,7 +39,7 @@ function getLoginHtml(defaultUsername: string): string {
   }
 
   const escapedUsername = escapeHtml(defaultUsername)
-  return cachedLoginTemplate.replace(/\{\{DEFAULT_USERNAME\}\}/g, escapedUsername)
+  return cachedLoginTemplate.replace(/\{\{DEFAULT_USERNAME\}\}/g, () => escapedUsername)
 }
 
 function getTokenHtml(): string {
diff --git a/packages/server/src/server/routes/opencode-update.test.ts b/packages/server/src/server/routes/opencode-update.test.ts
new file mode 100644
index 00000000..ef0f6004
--- /dev/null
+++ b/packages/server/src/server/routes/opencode-update.test.ts
@@ -0,0 +1,39 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import Fastify from "fastify"
+import type { Logger } from "../../logger"
+import type { OpenCodeUpdateService } from "../../opencode-update/service"
+import { registerOpenCodeUpdateRoutes } from "./opencode-update"
+
+test("does not pass request-controlled binary paths to the update service", async () => {
+  const calls: Array<{ method: string; args: unknown[] }> = []
+  const service = {
+    getStatus: async (...args: unknown[]) => {
+      calls.push({ method: "status", args })
+      return {
+        currentVersion: "1.0.0",
+        latestVersion: "1.1.0",
+        updateAvailable: true,
+        canUpgrade: true,
+      }
+    },
+    upgrade: async (...args: unknown[]) => {
+      calls.push({ method: "upgrade", args })
+      return { success: true, version: "1.1.0" }
+    },
+  } as unknown as OpenCodeUpdateService
+  const app = Fastify()
+  registerOpenCodeUpdateRoutes(app, {
+    service,
+    logger: { warn() {} } as unknown as Logger,
+  })
+
+  await app.inject({ method: "GET", url: "/api/opencode/update?binary=untrusted.cmd" })
+  await app.inject({ method: "POST", url: "/api/opencode/update", payload: { binary: "untrusted.cmd" } })
+
+  assert.deepEqual(calls, [
+    { method: "status", args: [] },
+    { method: "upgrade", args: [] },
+  ])
+  await app.close()
+})
diff --git a/packages/server/src/server/routes/opencode-update.ts b/packages/server/src/server/routes/opencode-update.ts
new file mode 100644
index 00000000..58e328d0
--- /dev/null
+++ b/packages/server/src/server/routes/opencode-update.ts
@@ -0,0 +1,43 @@
+import type { FastifyInstance } from "fastify"
+import type { Logger } from "../../logger"
+import { OpenCodeUpdateError, type OpenCodeUpdateService } from "../../opencode-update/service"
+
+interface RouteDeps {
+  service: OpenCodeUpdateService
+  logger: Logger
+}
+
+function statusCode(error: OpenCodeUpdateError): number {
+  if (error.code === "no_ready_instance") return 409
+  if (error.code === "binary_unavailable") return 422
+  return 502
+}
+
+function requestError(error: unknown, fallback: string): { status: number; code: string } {
+  if (error instanceof OpenCodeUpdateError) return { status: statusCode(error), code: error.code }
+  return { status: 500, code: fallback }
+}
+
+export function registerOpenCodeUpdateRoutes(app: FastifyInstance, deps: RouteDeps) {
+  app.get("/api/opencode/update", async (_request, reply) => {
+    try {
+      return await deps.service.getStatus()
+    } catch (error) {
+      deps.logger.warn({ err: error }, "Failed to check OpenCode update status")
+      const failure = requestError(error, "update_check_failed")
+      reply.code(failure.status)
+      return { error: failure.code }
+    }
+  })
+
+  app.post("/api/opencode/update", async (_request, reply) => {
+    try {
+      return await deps.service.upgrade()
+    } catch (error) {
+      deps.logger.warn({ err: error }, "Failed to update OpenCode")
+      const failure = requestError(error, "upgrade_failed")
+      reply.code(failure.status)
+      return { success: false, error: failure.code }
+    }
+  })
+}
diff --git a/packages/server/src/server/routes/settings.test.ts b/packages/server/src/server/routes/settings.test.ts
new file mode 100644
index 00000000..53d27cbf
--- /dev/null
+++ b/packages/server/src/server/routes/settings.test.ts
@@ -0,0 +1,87 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { enforceSpeechCredentialPairing } from "./settings"
+
+describe("enforceSpeechCredentialPairing", () => {
+  it("clears shared key when baseUrl differs from stored", () => {
+    const result = enforceSpeechCredentialPairing(
+      { speech: { baseUrl: "https://new.com/v1" } },
+      { speech: { baseUrl: "https://old.com/v1", apiKey: "sk-stored" } },
+    ) as any
+    assert.equal(result.speech.apiKey, null)
+  })
+
+  it("does NOT clear shared key when baseUrl matches stored (old client full patch)", () => {
+    const result = enforceSpeechCredentialPairing(
+      { speech: { baseUrl: "https://api.openai.com/v1", ttsVoice: "alloy", playbackMode: "streaming" } },
+      { speech: { baseUrl: "https://api.openai.com/v1", apiKey: "sk-stored" } },
+    ) as any
+    assert.equal("apiKey" in result.speech, false, "must not clear key when URL unchanged")
+  })
+
+  it("clears directional key when directional baseUrl differs from stored", () => {
+    const result = enforceSpeechCredentialPairing(
+      { speech: { stt: { baseUrl: "https://new.com/v1" } } },
+      { speech: { stt: { baseUrl: "https://old.com/v1", apiKey: "sk-stored" } } },
+    ) as any
+    assert.equal(result.speech.stt.apiKey, null)
+  })
+
+  it("does NOT clear directional key when baseUrl matches stored", () => {
+    const result = enforceSpeechCredentialPairing(
+      { speech: { stt: { baseUrl: "https://same.com/v1", model: "whisper-1" } } },
+      { speech: { stt: { baseUrl: "https://same.com/v1", apiKey: "sk-stored" } } },
+    ) as any
+    assert.equal("apiKey" in result.speech.stt, false, "must not clear directional key when URL unchanged")
+  })
+
+  it("preserves apiKey when both baseUrl and apiKey are in patch", () => {
+    const result = enforceSpeechCredentialPairing(
+      { speech: { baseUrl: "https://new.com/v1", apiKey: "sk-new" } },
+      { speech: { baseUrl: "https://old.com/v1", apiKey: "sk-old" } },
+    ) as any
+    assert.equal(result.speech.apiKey, "sk-new")
+  })
+
+  it("handles both stt and tts independently against stored values", () => {
+    const result = enforceSpeechCredentialPairing(
+      { speech: { stt: { baseUrl: "https://stt-same.com/v1", apiKey: "sk-stt" }, tts: { baseUrl: "https://tts-new.com/v1" } } },
+      { speech: { stt: { baseUrl: "https://stt-same.com/v1", apiKey: "sk-stt" }, tts: { baseUrl: "https://tts-old.com/v1", apiKey: "sk-tts" } } },
+    ) as any
+    assert.equal(result.speech.stt.apiKey, "sk-stt")
+    assert.equal(result.speech.tts.apiKey, null)
+  })
+
+  it("passes through non-speech patches unchanged", () => {
+    const body = { logLevel: "INFO" }
+    const result = enforceSpeechCredentialPairing(body, { speech: {} })
+    assert.deepEqual(result, body)
+  })
+
+  it("passes through null/undefined body", () => {
+    assert.equal(enforceSpeechCredentialPairing(null), null)
+    assert.equal(enforceSpeechCredentialPairing(undefined), undefined)
+  })
+
+  it("does not mutate the original body", () => {
+    const original = { speech: { baseUrl: "https://new.com/v1" } }
+    const originalCopy = JSON.parse(JSON.stringify(original))
+    enforceSpeechCredentialPairing(original, { speech: { baseUrl: "https://old.com/v1" } })
+    assert.deepEqual(original, originalCopy)
+  })
+
+  it("doc-level payload: clears key when server.speech.baseUrl changes", () => {
+    const docBody = { server: { speech: { baseUrl: "https://new.com/v1" } } }
+    const currentServer = { speech: { baseUrl: "https://old.com/v1", apiKey: "sk-stored" } }
+    const result = enforceSpeechCredentialPairing(docBody.server, currentServer) as any
+    assert.equal(result.speech.apiKey, null, "doc-level server.speech must have key cleared on URL change")
+    assert.equal(result.speech.baseUrl, "https://new.com/v1")
+  })
+
+  it("doc-level payload: preserves key when server.speech.baseUrl unchanged", () => {
+    const docBody = { server: { speech: { baseUrl: "https://same.com/v1", ttsVoice: "alloy" } } }
+    const currentServer = { speech: { baseUrl: "https://same.com/v1", apiKey: "sk-stored" } }
+    const result = enforceSpeechCredentialPairing(docBody.server, currentServer) as any
+    assert.equal("apiKey" in result.speech, false, "key must not be cleared when URL unchanged in doc-level patch")
+  })
+})
diff --git a/packages/server/src/server/routes/settings.ts b/packages/server/src/server/routes/settings.ts
index 5d18e4fd..57de9545 100644
--- a/packages/server/src/server/routes/settings.ts
+++ b/packages/server/src/server/routes/settings.ts
@@ -19,12 +19,52 @@ function validateBinaryPath(binaryPath: string): { valid: boolean; version?: str
   return { valid: result.valid, version: result.version, error: result.error }
 }
 
+export function enforceSpeechCredentialPairing(body: unknown, currentSpeech?: unknown): unknown {
+  if (!body || typeof body !== "object") return body
+  const patch = { ...(body as Record<string, unknown>) }
+  const speech = patch.speech
+  if (!speech || typeof speech !== "object") return patch
+  const speechPatch = { ...(speech as Record<string, unknown>) }
+  const cur = (currentSpeech && typeof currentSpeech === "object") ? currentSpeech as Record<string, unknown> : {}
+  const curSpeech = (cur.speech && typeof cur.speech === "object") ? cur.speech as Record<string, unknown> : cur
+
+  if ("baseUrl" in speechPatch && !("apiKey" in speechPatch)) {
+    if ((speechPatch.baseUrl ?? "") !== (curSpeech.baseUrl ?? "")) {
+      speechPatch.apiKey = null
+    }
+  }
+  for (const dir of ["stt", "tts"] as const) {
+    if (dir in speechPatch) {
+      const dirPatch = { ...(speechPatch[dir] as Record<string, unknown>) }
+      if ("baseUrl" in dirPatch && !("apiKey" in dirPatch)) {
+        const curDir = (curSpeech[dir] && typeof curSpeech[dir] === "object") ? curSpeech[dir] as Record<string, unknown> : {}
+        if ((dirPatch.baseUrl ?? "") !== (curDir.baseUrl ?? "")) {
+          dirPatch.apiKey = null
+        }
+        speechPatch[dir] = dirPatch
+      }
+    }
+  }
+  patch.speech = speechPatch
+  return patch
+}
+
 export function registerSettingsRoutes(app: FastifyInstance, deps: RouteDeps) {
   // Full-document access
   app.get("/api/storage/config", async () => sanitizeConfigDoc(deps.settings.getDoc("config")))
   app.patch("/api/storage/config", async (request, reply) => {
     try {
-      return sanitizeConfigDoc(deps.settings.mergePatchDoc("config", request.body ?? {}))
+      let body = request.body ?? {}
+      if (body && typeof body === "object" && "server" in body) {
+        const bodyObj = { ...(body as Record<string, unknown>) }
+        const serverPatch = bodyObj.server
+        if (serverPatch && typeof serverPatch === "object") {
+          const currentServer = deps.settings.getOwner("config", "server")
+          bodyObj.server = enforceSpeechCredentialPairing(serverPatch, currentServer)
+        }
+        body = bodyObj
+      }
+      return sanitizeConfigDoc(deps.settings.mergePatchDoc("config", body))
     } catch (error) {
       reply.code(400)
       return { error: error instanceof Error ? error.message : "Invalid patch" }
@@ -37,9 +77,15 @@ export function registerSettingsRoutes(app: FastifyInstance, deps: RouteDeps) {
 
   app.patch<{ Params: { owner: string } }>("/api/storage/config/:owner", async (request, reply) => {
     try {
+      const currentOwner = request.params.owner === "server"
+        ? deps.settings.getOwner("config", "server")
+        : undefined
+      const processed = request.params.owner === "server"
+        ? enforceSpeechCredentialPairing(request.body ?? {}, currentOwner)
+        : request.body ?? {}
       return sanitizeConfigOwner(
         request.params.owner,
-        deps.settings.mergePatchOwner("config", request.params.owner, request.body ?? {}),
+        deps.settings.mergePatchOwner("config", request.params.owner, processed),
       )
     } catch (error) {
       reply.code(400)
diff --git a/packages/server/src/server/routes/usage.test.ts b/packages/server/src/server/routes/usage.test.ts
new file mode 100644
index 00000000..ef4ca118
--- /dev/null
+++ b/packages/server/src/server/routes/usage.test.ts
@@ -0,0 +1,28 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import Fastify from "fastify"
+
+import { registerUsageRoutes } from "./usage"
+
+test("returns a typed unsupported result without exposing server details", async () => {
+  const app = Fastify()
+  registerUsageRoutes(app)
+
+  try {
+    const response = await app.inject({ method: "GET", url: "/api/usage/unknown-provider?modelId=test-model" })
+    assert.equal(response.statusCode, 200)
+    assert.deepEqual(response.json(), {
+      requestedProviderId: "unknown-provider",
+      providerId: null,
+      providerName: "unknown-provider",
+      modelId: "test-model",
+      supported: false,
+      configured: false,
+      ok: false,
+      windows: {},
+      fetchedAt: response.json().fetchedAt,
+    })
+  } finally {
+    await app.close()
+  }
+})
diff --git a/packages/server/src/server/routes/usage.ts b/packages/server/src/server/routes/usage.ts
new file mode 100644
index 00000000..24e41473
--- /dev/null
+++ b/packages/server/src/server/routes/usage.ts
@@ -0,0 +1,24 @@
+import type { FastifyInstance } from "fastify"
+import { z } from "zod"
+
+import { getProviderUsage } from "../../usage/service"
+
+const UsageParamsSchema = z.object({ providerId: z.string().trim().min(1) })
+const UsageQuerySchema = z.object({ modelId: z.string().trim().optional() })
+
+export function registerUsageRoutes(app: FastifyInstance) {
+  app.get<{ Params: { providerId: string }; Querystring: { modelId?: string } }>(
+    "/api/usage/:providerId",
+    async (request, reply) => {
+      try {
+        const params = UsageParamsSchema.parse(request.params)
+        const query = UsageQuerySchema.parse(request.query ?? {})
+        return await getProviderUsage(params.providerId, { modelId: query.modelId })
+      } catch (error) {
+        request.log.error({ err: error }, "Failed to fetch provider usage")
+        reply.code(400)
+        return { error: error instanceof Error ? error.message : "Failed to fetch provider usage" }
+      }
+    },
+  )
+}
diff --git a/packages/server/src/server/routes/workspaces.test.ts b/packages/server/src/server/routes/workspaces.test.ts
new file mode 100644
index 00000000..e115c5b7
--- /dev/null
+++ b/packages/server/src/server/routes/workspaces.test.ts
@@ -0,0 +1,126 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import Fastify from "fastify"
+
+import type { WorkspaceDescriptor } from "../../api-types"
+import type { WorkspaceManager } from "../../workspaces/manager"
+import { registerWorkspaceRoutes } from "./workspaces"
+
+describe("workspace routes", () => {
+  it("forwards a validated explicit binary path when creating a workspace", async () => {
+    const calls: unknown[][] = []
+    const app = Fastify({ logger: false })
+    const descriptor: WorkspaceDescriptor = {
+      id: "workspace",
+      path: "C:/work",
+      status: "ready",
+      proxyPath: "/workspaces/workspace/instance",
+      binaryId: "C:/tools/opencode.exe",
+      binaryLabel: "opencode.exe",
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    }
+    const workspaceManager = {
+      create: async (...args: unknown[]) => {
+        calls.push(args)
+        return { workspace: descriptor, created: true }
+      },
+      releaseCreationRequest: (workspaceId: string, requestId: string) =>
+        workspaceId === descriptor.id && requestId === "restore-request",
+      cancelCreationRequest: async (requestId: string) => {
+        calls.push(["cancel", requestId])
+      },
+    } as unknown as WorkspaceManager
+    registerWorkspaceRoutes(app, { workspaceManager })
+
+    const response = await app.inject({
+      method: "POST",
+      url: "/api/workspaces",
+      payload: {
+        path: "C:/work",
+        name: "Work",
+        binaryPath: " C:/tools/opencode.exe ",
+        requestId: " restore-request ",
+        forceNew: true,
+      },
+    })
+
+    assert.equal(response.statusCode, 201)
+    assert.deepEqual(calls, [["C:/work", "Work", {
+      binaryPath: "C:/tools/opencode.exe",
+      requestId: "restore-request",
+      forceNew: true,
+    }]])
+
+    const released = await app.inject({
+      method: "POST",
+      url: "/api/workspaces/workspace/creation/release",
+      payload: { requestId: "restore-request" },
+    })
+    assert.equal(released.statusCode, 204)
+
+    const wrongRelease = await app.inject({
+      method: "POST",
+      url: "/api/workspaces/workspace/creation/release",
+      payload: { requestId: "other-request" },
+    })
+    assert.equal(wrongRelease.statusCode, 404)
+
+    const cancelled = await app.inject({
+      method: "POST",
+      url: "/api/workspaces/creation/cancel",
+      payload: { requestId: "restore-request" },
+    })
+    assert.equal(cancelled.statusCode, 204)
+    assert.deepEqual(calls.at(-1), ["cancel", "restore-request"])
+
+    const invalid = await app.inject({
+      method: "POST",
+      url: "/api/workspaces",
+      payload: { path: "C:/work", binaryPath: "x".repeat(4097) },
+    })
+    assert.equal(invalid.statusCode, 400)
+    assert.equal(calls.length, 2)
+    await app.close()
+  })
+
+  it("rejects release after cancellation wins while deletion is still pending", async () => {
+    const app = Fastify({ logger: false })
+    let state: "active" | "cancelled" | "released" = "active"
+    let cancellationStarted!: () => void
+    let finishDeletion!: () => void
+    const started = new Promise<void>((resolve) => { cancellationStarted = resolve })
+    const deletion = new Promise<void>((resolve) => { finishDeletion = resolve })
+    const workspaceManager = {
+      cancelCreationRequest: async () => {
+        state = "cancelled"
+        cancellationStarted()
+        await deletion
+      },
+      releaseCreationRequest: () => {
+        if (state === "cancelled") return false
+        state = "released"
+        return true
+      },
+    } as unknown as WorkspaceManager
+    registerWorkspaceRoutes(app, { workspaceManager })
+
+    const cancellation = app.inject({
+      method: "POST",
+      url: "/api/workspaces/creation/cancel",
+      payload: { requestId: "restore-request" },
+    })
+    await started
+    const release = await app.inject({
+      method: "POST",
+      url: "/api/workspaces/workspace/creation/release",
+      payload: { requestId: "restore-request" },
+    })
+
+    assert.equal(release.statusCode, 404)
+    assert.equal(release.body, "Workspace creation request not found")
+    finishDeletion()
+    assert.equal((await cancellation).statusCode, 204)
+    await app.close()
+  })
+})
diff --git a/packages/server/src/server/routes/workspaces.ts b/packages/server/src/server/routes/workspaces.ts
index 7bb8a1b0..e7f05213 100644
--- a/packages/server/src/server/routes/workspaces.ts
+++ b/packages/server/src/server/routes/workspaces.ts
@@ -14,6 +14,9 @@ interface RouteDeps {
 const WorkspaceCreateSchema = z.object({
   path: z.string(),
   name: z.string().optional(),
+  binaryPath: z.string().trim().min(1).max(4096).optional(),
+  requestId: z.string().trim().min(1).max(128).optional(),
+  forceNew: z.boolean().optional(),
 })
 
 const WorkspaceCloneSchema = z.object({
@@ -22,6 +25,10 @@ const WorkspaceCloneSchema = z.object({
   cleanup: z.boolean().optional(),
 })
 
+const WorkspaceCreationReleaseSchema = z.object({
+  requestId: z.string().trim().min(1).max(128),
+})
+
 const WorkspaceFilesQuerySchema = z.object({
   path: z.string().optional(),
 })
@@ -68,9 +75,13 @@ export function registerWorkspaceRoutes(app: FastifyInstance, deps: RouteDeps) {
   app.post("/api/workspaces", async (request, reply) => {
     try {
       const body = WorkspaceCreateSchema.parse(request.body ?? {})
-      const workspace = await deps.workspaceManager.create(body.path, body.name)
+      const result = await deps.workspaceManager.create(body.path, body.name, {
+        binaryPath: body.binaryPath,
+        requestId: body.requestId,
+        forceNew: body.forceNew,
+      })
       reply.code(201)
-      return workspace
+      return result.created ? result.workspace : { ...result.workspace, reused: true as const }
     } catch (error) {
       request.log.error({ err: error }, "Failed to create workspace")
       const message = error instanceof Error ? error.message : "Failed to create workspace"
@@ -103,6 +114,30 @@ export function registerWorkspaceRoutes(app: FastifyInstance, deps: RouteDeps) {
     reply.code(204)
   })
 
+  app.post("/api/workspaces/creation/cancel", async (request, reply) => {
+    const parsed = WorkspaceCreationReleaseSchema.safeParse(request.body ?? {})
+    if (!parsed.success) {
+      reply.code(400).type("text/plain").send("Invalid workspace creation request")
+      return
+    }
+    await deps.workspaceManager.cancelCreationRequest(parsed.data.requestId)
+    reply.code(204)
+  })
+
+  app.post<{ Params: { id: string } }>("/api/workspaces/:id/creation/release", async (request, reply) => {
+    const parsed = WorkspaceCreationReleaseSchema.safeParse(request.body ?? {})
+    if (!parsed.success) {
+      reply.code(400).type("text/plain").send("Invalid workspace creation request")
+      return
+    }
+    const body = parsed.data
+    if (!deps.workspaceManager.releaseCreationRequest(request.params.id, body.requestId)) {
+      reply.code(404).type("text/plain").send("Workspace creation request not found")
+      return
+    }
+    reply.code(204)
+  })
+
   app.get<{
     Params: { id: string }
     Querystring: { path?: string }
diff --git a/packages/server/src/server/routes/worktrees.ts b/packages/server/src/server/routes/worktrees.ts
index 9e76319b..d48d9ddb 100644
--- a/packages/server/src/server/routes/worktrees.ts
+++ b/packages/server/src/server/routes/worktrees.ts
@@ -9,10 +9,12 @@ import {
   removeWorktree,
 } from "../../workspaces/git-worktrees"
 import type { WorktreeListResponse, WorktreeMap } from "../../api-types"
+import type { OpencodeYoloPersistence } from "../../permissions/opencode-yolo-metadata"
 import { ensureCodenomadGitExclude, readWorktreeMap, writeWorktreeMap } from "../../workspaces/worktree-map"
 
 interface RouteDeps {
   workspaceManager: WorkspaceManager
+  sessionMetadataPersistence: OpencodeYoloPersistence
 }
 
 const WorktreeMapSchema = z.object({
@@ -26,7 +28,34 @@ const WorktreeCreateSchema = z.object({
   branch: z.string().trim().min(1).optional(),
 })
 
+const WorktreeSessionSchema = z.object({ worktreeSlug: z.string().trim().refine(isValidWorktreeSlug) })
+
 export function registerWorktreeRoutes(app: FastifyInstance, deps: RouteDeps) {
+  app.put<{ Params: { id: string; sessionId: string }; Body: unknown }>(
+    "/api/workspaces/:id/worktrees/sessions/:sessionId",
+    async (request, reply) => {
+      if (!deps.workspaceManager.get(request.params.id)) {
+        reply.code(404)
+        return { error: "Workspace not found" }
+      }
+      try {
+        const body = WorktreeSessionSchema.parse(request.body)
+        if (!await deps.sessionMetadataPersistence.hasProjectSession(request.params.id, request.params.sessionId)) {
+          reply.code(404)
+          return { error: "Session not found" }
+        }
+        const metadata = await deps.sessionMetadataPersistence.setWorktreeSlug(
+          request.params.id,
+          request.params.sessionId,
+          body.worktreeSlug,
+        )
+        return { metadata }
+      } catch (error) {
+        return handleError(error, reply)
+      }
+    },
+  )
+
   app.get<{ Params: { id: string } }>("/api/workspaces/:id/worktrees", async (request, reply) => {
     const workspace = deps.workspaceManager.get(request.params.id)
     if (!workspace) {
diff --git a/packages/server/src/server/routes/yolo.ts b/packages/server/src/server/routes/yolo.ts
new file mode 100644
index 00000000..42341431
--- /dev/null
+++ b/packages/server/src/server/routes/yolo.ts
@@ -0,0 +1,27 @@
+import { FastifyInstance } from "fastify"
+import type { AutoAcceptManager } from "../../permissions/auto-accept-manager"
+
+interface RouteDeps {
+  yoloManager: AutoAcceptManager
+}
+
+export function registerYoloRoutes(app: FastifyInstance, deps: RouteDeps) {
+  app.get<{ Params: { id: string; sessionId: string } }>(
+    "/workspaces/:id/yolo/sessions/:sessionId",
+    async (request) => {
+      const { id, sessionId } = request.params
+      await deps.yoloManager.hydrateInstance(id)
+      return { enabled: deps.yoloManager.isEnabled(id, sessionId) }
+    },
+  )
+
+  app.post<{ Params: { id: string; sessionId: string } }>(
+    "/workspaces/:id/yolo/sessions/:sessionId/toggle",
+    async (request, reply) => {
+      const { id, sessionId } = request.params
+      const enabled = await deps.yoloManager.toggle(id, sessionId)
+      reply.code(200)
+      return { enabled }
+    },
+  )
+}
diff --git a/packages/server/src/settings/binaries.test.ts b/packages/server/src/settings/binaries.test.ts
new file mode 100644
index 00000000..5c3fc86d
--- /dev/null
+++ b/packages/server/src/settings/binaries.test.ts
@@ -0,0 +1,20 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { BinaryResolver } from "./binaries"
+import type { SettingsService } from "./service"
+
+describe("BinaryResolver", () => {
+  it("uses an explicit workspace binary without changing the configured default", () => {
+    const settings = {
+      getOwner(scope: string, owner: string) {
+        if (scope === "config" && owner === "server") return { opencodeBinary: "default-opencode" }
+        if (scope === "state" && owner === "ui") return { opencodeBinaries: [{ path: "saved-opencode", label: "Saved", version: "1.2.3" }] }
+        return {}
+      },
+    } as unknown as SettingsService
+    const resolver = new BinaryResolver(settings)
+    assert.deepEqual(resolver.resolve("saved-opencode"), { path: "saved-opencode", label: "Saved", version: "1.2.3" })
+    assert.equal(resolver.resolveDefault().path, "default-opencode")
+  })
+})
diff --git a/packages/server/src/settings/binaries.ts b/packages/server/src/settings/binaries.ts
index e4b25960..d637ac95 100644
--- a/packages/server/src/settings/binaries.ts
+++ b/packages/server/src/settings/binaries.ts
@@ -40,10 +40,14 @@ export class BinaryResolver {
   }
 
   resolveDefault(): ResolvedBinary {
+    return this.resolve()
+  }
+
+  resolve(explicitPath?: string): ResolvedBinary {
     const binaries = this.list()
     const configuredDefault = readDefaultBinaryPath(this.settings)
     const fallback = binaries[0]?.path
-    const path = configuredDefault ?? fallback ?? "opencode"
+    const path = explicitPath?.trim() || configuredDefault || fallback || "opencode"
 
     const entry = binaries.find((b) => b.path === path)
     return {
diff --git a/packages/server/src/settings/public-config.test.ts b/packages/server/src/settings/public-config.test.ts
new file mode 100644
index 00000000..afe66640
--- /dev/null
+++ b/packages/server/src/settings/public-config.test.ts
@@ -0,0 +1,61 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { sanitizeConfigOwner } from "./public-config"
+
+describe("sanitizeConfigOwner server speech", () => {
+  it("strips shared apiKey and sets hasApiKey", () => {
+    const result = sanitizeConfigOwner("server", {
+      speech: { apiKey: "sk-secret", sttModel: "whisper-1" },
+    })
+    assert.equal((result.speech as any).apiKey, undefined)
+    assert.equal((result.speech as any).hasApiKey, true)
+  })
+
+  it("strips stt.apiKey and sets stt.hasApiKey when separateProviders is true", () => {
+    const result = sanitizeConfigOwner("server", {
+      speech: {
+        separateProviders: true,
+        apiKey: "sk-shared",
+        stt: { apiKey: "sk-stt-secret", baseUrl: "https://groq.com" },
+        tts: { apiKey: "sk-tts-secret", baseUrl: "https://openai.com" },
+      },
+    })
+    assert.equal((result.speech as any).apiKey, undefined)
+    assert.equal((result.speech as any).hasApiKey, true)
+    assert.equal((result.speech as any).stt.apiKey, undefined)
+    assert.equal((result.speech as any).stt.hasApiKey, true)
+    assert.equal((result.speech as any).tts.apiKey, undefined)
+    assert.equal((result.speech as any).tts.hasApiKey, true)
+  })
+
+  it("sets hasApiKey=false when per-direction apiKey is absent", () => {
+    const result = sanitizeConfigOwner("server", {
+      speech: {
+        separateProviders: true,
+        stt: { baseUrl: "https://groq.com" },
+        tts: { baseUrl: "https://openai.com" },
+      },
+    })
+    assert.equal((result.speech as any).stt.hasApiKey, false)
+    assert.equal((result.speech as any).tts.hasApiKey, false)
+  })
+
+  it("preserves stt/tts sub-objects that have no apiKey", () => {
+    const result = sanitizeConfigOwner("server", {
+      speech: {
+        separateProviders: true,
+        stt: { model: "whisper-large-v3" },
+        tts: { model: "tts-1" },
+      },
+    })
+    assert.equal((result.speech as any).stt.model, "whisper-large-v3")
+    assert.equal((result.speech as any).stt.hasApiKey, false)
+    assert.equal((result.speech as any).tts.model, "tts-1")
+    assert.equal((result.speech as any).tts.hasApiKey, false)
+  })
+
+  it("passes through non-server owners unchanged", () => {
+    const result = sanitizeConfigOwner("ui", { foo: "bar" })
+    assert.deepEqual(result, { foo: "bar" })
+  })
+})
diff --git a/packages/server/src/settings/public-config.ts b/packages/server/src/settings/public-config.ts
index a79a0222..a3eb26a7 100644
--- a/packages/server/src/settings/public-config.ts
+++ b/packages/server/src/settings/public-config.ts
@@ -20,6 +20,20 @@ function sanitizeServerOwner(value: SettingsDoc): SettingsDoc {
     speech.hasApiKey = false
   }
 
+  for (const dir of ["stt", "tts"] as const) {
+    if (isPlainObject(speech[dir])) {
+      const sub = { ...speech[dir] } as SettingsDoc
+      const dirKey = typeof sub.apiKey === "string" ? sub.apiKey.trim() : ""
+      if (dirKey) {
+        delete sub.apiKey
+        sub.hasApiKey = true
+      } else if (!("hasApiKey" in sub)) {
+        sub.hasApiKey = false
+      }
+      speech[dir] = sub
+    }
+  }
+
   next.speech = speech
   return next
 }
diff --git a/packages/server/src/shutdown.test.ts b/packages/server/src/shutdown.test.ts
new file mode 100644
index 00000000..446e7791
--- /dev/null
+++ b/packages/server/src/shutdown.test.ts
@@ -0,0 +1,162 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import {
+  createServerShutdownHandler,
+  orchestrateServerShutdown,
+  SERVER_SHUTDOWN_COMPLETE,
+  SERVER_SHUTDOWN_INCOMPLETE,
+  type ServerShutdownOperations,
+} from "./shutdown"
+
+const logger = { info() {}, warn() {}, error() {} }
+const operations = (overrides: Partial<ServerShutdownOperations> = {}): ServerShutdownOperations => ({
+  stopInstanceEventBridge() {}, stopSidecars() {}, stopClientConnections() {},
+  stopRemoteProxySessions() {}, stopWorkspaces() {}, stopHttpServers() {}, stopReleaseMonitor() {},
+  ...overrides,
+})
+
+describe("server shutdown orchestration", () => {
+  it("retries workspace cleanup and preserves shutdown order", async () => {
+    const calls: string[] = []
+    let attempts = 0
+    await orchestrateServerShutdown(operations({
+      stopRemoteProxySessions: () => { calls.push("remote-proxy") },
+      stopWorkspaces: () => { calls.push(`workspaces-${++attempts}`); if (attempts === 1) throw new Error("still alive") },
+      stopHttpServers: () => { calls.push("http") },
+    }), logger)
+    assert.deepEqual(calls, ["workspaces-1", "remote-proxy", "workspaces-2", "http"])
+  })
+
+  it("closes remaining resources and aggregates the concrete current error", async () => {
+    const failure = new Error("workspace abc POSIX process group is still alive")
+    const closed: string[] = []
+    let attempts = 0
+    await assert.rejects(orchestrateServerShutdown(operations({
+      stopWorkspaces: () => { attempts++; throw failure },
+      stopHttpServers: () => { closed.push("http") },
+      stopReleaseMonitor: () => { closed.push("release-monitor") },
+    }), logger), (error: unknown) => {
+      assert.ok(error instanceof AggregateError)
+      assert.equal(error.errors.length, 1)
+      assert.match(error.errors[0].message, /^stopWorkspaces failed:/)
+      assert.strictEqual(error.errors[0].cause, failure)
+      return true
+    })
+    assert.deepEqual([attempts, closed], [2, ["http", "release-monitor"]])
+  })
+
+  it("starts workspace cleanup without waiting for preliminary shutdown", async () => {
+    let releasePreliminary!: () => void
+    const preliminary = new Promise<void>((resolve) => { releasePreliminary = resolve })
+    let workspaceStarted = false
+    const shutdown = orchestrateServerShutdown(operations({
+      stopRemoteProxySessions: () => preliminary,
+      stopWorkspaces: () => { workspaceStarted = true },
+    }), logger)
+
+    await new Promise<void>((resolve) => setImmediate(resolve))
+    assert.equal(workspaceStarted, true)
+    releasePreliminary()
+    await shutdown
+  })
+})
+
+describe("server shutdown signal boundary", () => {
+  it("reports incomplete cleanup and holds for final tree enforcement", async () => {
+    const calls: string[] = []
+    const exits: number[] = []
+    const statuses: string[] = []
+    let releaseHold!: () => void
+    const hold = new Promise<void>((resolve) => { releaseHold = resolve })
+    const handler = createServerShutdownHandler({
+      shutdown: async () => { calls.push("cleanup"); throw new Error("retained child survived") },
+      logger: { info: () => calls.push("info"), warn() {}, error: () => calls.push("error") },
+      forceExit: (code) => { calls.push("force-exit"); exits.push(code) },
+      setExitCode: () => undefined,
+      reportStatus: (status) => statuses.push(status),
+      holdAfterFailure: () => hold,
+      retryAttempts: 0,
+    })
+    const pending = handler("SIGTERM")
+    await new Promise<void>((resolve) => setImmediate(resolve))
+    assert.deepEqual([exits, statuses, calls], [[], [SERVER_SHUTDOWN_INCOMPLETE], ["info", "cleanup", "error", "error"]])
+    handler("SIGTERM")
+    assert.deepEqual(exits, [1])
+    releaseHold()
+    await pending
+  })
+
+  it("reports complete cleanup before allowing natural exit", async () => {
+    const statuses: string[] = [], exitCodes: number[] = []
+    const handler = createServerShutdownHandler({
+      shutdown: async () => undefined,
+      logger,
+      reportStatus: (status) => statuses.push(status),
+      setExitCode: (code) => exitCodes.push(code),
+    })
+    await handler("stdin")
+    assert.deepEqual(statuses, [SERVER_SHUTDOWN_COMPLETE])
+    assert.deepEqual(exitCodes, [0])
+  })
+
+  it("keeps retrying identity-aware cleanup during the final enforcement budget", async () => {
+    let attempts = 0
+    const statuses: string[] = [], exitCodes: number[] = []
+    const handler = createServerShutdownHandler({
+      shutdown: async () => {
+        attempts++
+        if (attempts === 1) throw new Error("detached group still alive")
+      },
+      logger,
+      reportStatus: (status) => statuses.push(status),
+      setExitCode: (code) => exitCodes.push(code),
+      retryDelayMs: 0,
+    })
+
+    await handler("stdin")
+    assert.equal(attempts, 2)
+    assert.deepEqual(statuses, [SERVER_SHUTDOWN_COMPLETE])
+    assert.deepEqual(exitCodes, [0])
+  })
+
+  it("preserves containment after the standalone cleanup retry budget", async () => {
+    let attempts = 0
+    const statuses: string[] = [], exitCodes: number[] = [], forcedExits: number[] = []
+    let releaseHold!: () => void
+    const hold = new Promise<void>((resolve) => { releaseHold = resolve })
+    const handler = createServerShutdownHandler({
+      shutdown: async () => { attempts++; throw new Error("process tree remains alive") },
+      logger,
+      reportStatus: (status) => statuses.push(status),
+      setExitCode: (code) => exitCodes.push(code),
+      forceExit: (code) => forcedExits.push(code),
+      holdAfterFailure: () => hold,
+      retryDelayMs: 0,
+      retryAttempts: 2,
+    })
+
+    const pending = handler("stdin")
+    while (attempts < 3) await new Promise<void>((resolve) => setTimeout(resolve, 0))
+    assert.equal(attempts, 3)
+    assert.deepEqual(statuses, [SERVER_SHUTDOWN_INCOMPLETE])
+    assert.deepEqual(exitCodes, [1])
+    assert.deepEqual(forcedExits, [])
+    handler("SIGTERM")
+    assert.deepEqual(forcedExits, [1])
+    releaseHold()
+    await pending
+  })
+
+  it("escalates a second signal while sharing first-signal cleanup", async () => {
+    let finish!: () => void
+    const cleanup = new Promise<void>((resolve) => { finish = resolve })
+    const exits: number[] = [], exitCodes: number[] = []
+    const handler = createServerShutdownHandler({ shutdown: () => cleanup, logger,
+      forceExit: (code) => exits.push(code), setExitCode: (code) => exitCodes.push(code), reportStatus: () => undefined })
+    const first = handler("SIGINT"), second = handler("SIGTERM")
+    assert.strictEqual(first, second)
+    assert.deepEqual(exits, [1])
+    finish(); await first
+    assert.deepEqual(exitCodes, [0])
+  })
+})
diff --git a/packages/server/src/shutdown.ts b/packages/server/src/shutdown.ts
new file mode 100644
index 00000000..3324aa25
--- /dev/null
+++ b/packages/server/src/shutdown.ts
@@ -0,0 +1,101 @@
+type ShutdownLogger = Pick<import("./logger").Logger, "info" | "warn" | "error">
+type ShutdownOperation = () => void | Promise<void>
+
+export type ServerShutdownTrigger = NodeJS.Signals | "stdin"
+export const SERVER_SHUTDOWN_COMPLETE = "CODENOMAD_SHUTDOWN_STATUS:complete"
+export const SERVER_SHUTDOWN_INCOMPLETE = "CODENOMAD_SHUTDOWN_STATUS:incomplete"
+
+export type ServerShutdownOperations = Record<
+  "stopInstanceEventBridge" | "stopSidecars" | "stopClientConnections" | "stopRemoteProxySessions" | "stopWorkspaces" |
+  "stopHttpServers" | "stopReleaseMonitor",
+  ShutdownOperation
+>
+
+export function createServerShutdownHandler(options: { shutdown: () => Promise<void>; logger: ShutdownLogger;
+  forceExit?: (code: number) => void; setExitCode?: (code: number) => void;
+  reportStatus?: (status: string) => void; holdAfterFailure?: () => Promise<void>;
+  retryDelayMs?: number; retryAttempts?: number }) {
+  const forceExit = options.forceExit ?? process.exit
+  const setExitCode = options.setExitCode ?? ((code: number) => { process.exitCode = code })
+  const reportStatus = options.reportStatus ?? ((status: string) => console.log(status))
+  let pending: Promise<void> | undefined
+  return (signal: ServerShutdownTrigger): Promise<void> => {
+    if (pending) {
+      options.logger.error({ signal }, "Additional shutdown signal received; forcing nonzero exit")
+      forceExit(1)
+      return pending
+    }
+    options.logger.info({ signal }, "Received shutdown signal, stopping workspaces and server")
+    pending = Promise.resolve().then(options.shutdown).then(() => {
+      options.logger.info({}, "Shutdown complete")
+      reportStatus(SERVER_SHUTDOWN_COMPLETE)
+      setExitCode(0)
+    }, async (error) => {
+      options.logger.error({ err: error }, "Server shutdown incomplete; retrying cleanup")
+      const retryAttempts = Math.max(0, Math.floor(options.retryAttempts ?? 3))
+      for (let attempt = 1; attempt <= retryAttempts; attempt += 1) {
+        await new Promise<void>((resolve) => setTimeout(resolve, options.retryDelayMs ?? 250))
+        try {
+          await options.shutdown()
+          options.logger.info({}, "Shutdown cleanup retry completed")
+          reportStatus(SERVER_SHUTDOWN_COMPLETE)
+          setExitCode(0)
+          return
+        } catch (retryError) {
+          options.logger.warn({ err: retryError, attempt, attempts: retryAttempts }, "Shutdown cleanup retry remains incomplete")
+        }
+      }
+      options.logger.error({ attempts: retryAttempts }, "Shutdown cleanup retries exhausted; preserving process-tree containment")
+      reportStatus(SERVER_SHUTDOWN_INCOMPLETE)
+      setExitCode(1)
+      if (options.holdAfterFailure) await options.holdAfterFailure()
+    })
+    return pending
+  }
+}
+
+export async function orchestrateServerShutdown(
+  operations: ServerShutdownOperations,
+  logger: ShutdownLogger,
+  workspaceAttempts = 2,
+): Promise<void> {
+  const errors: unknown[] = []
+  const namedError = (name: keyof ServerShutdownOperations, cause: unknown) => Object.assign(
+    new Error(`${name} failed: ${cause instanceof Error ? cause.message : String(cause)}`),
+    { cause },
+  )
+  const settle = async (pending: Array<[keyof ServerShutdownOperations, ShutdownOperation]>) => {
+    const results = await Promise.allSettled(pending.map(([, run]) => Promise.resolve().then(run)))
+    for (let index = 0; index < results.length; index += 1) {
+      const result = results[index]!
+      if (result.status !== "rejected") continue
+      const error = namedError(pending[index]![0], result.reason)
+      errors.push(error)
+      logger.error({ err: error }, "Server resource shutdown failed")
+    }
+  }
+
+  const workspaceShutdown = (async () => {
+    const attempts = Math.max(1, Math.floor(workspaceAttempts))
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      const [result] = await Promise.allSettled([Promise.resolve().then(operations.stopWorkspaces)])
+      if (result.status === "fulfilled") break
+      if (attempt < attempts) {
+        logger.warn({ err: result.reason, attempt, attempts }, "Workspace manager shutdown failed; retrying cleanup")
+        continue
+      }
+      const error = namedError("stopWorkspaces", result.reason)
+      errors.push(error)
+      logger.error({ err: error, attempts }, "Workspace manager shutdown failed")
+    }
+  })()
+  await Promise.all([
+    settle([
+      ["stopInstanceEventBridge", operations.stopInstanceEventBridge], ["stopSidecars", operations.stopSidecars],
+      ["stopClientConnections", operations.stopClientConnections], ["stopRemoteProxySessions", operations.stopRemoteProxySessions],
+    ]),
+    workspaceShutdown,
+  ])
+  await settle([["stopHttpServers", operations.stopHttpServers], ["stopReleaseMonitor", operations.stopReleaseMonitor]])
+  if (errors.length) throw new AggregateError(errors, "Server shutdown failed")
+}
diff --git a/packages/server/src/speech/service.test.ts b/packages/server/src/speech/service.test.ts
new file mode 100644
index 00000000..66af0534
--- /dev/null
+++ b/packages/server/src/speech/service.test.ts
@@ -0,0 +1,289 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { SpeechService } from "./service"
+import type { SettingsService } from "../settings/service"
+import type { Logger } from "../logger"
+
+function createMockSettings(serverConfig: Record<string, unknown>): SettingsService {
+  return {
+    getOwner: () => serverConfig,
+  } as unknown as SettingsService
+}
+
+const mockLogger: Logger = {
+  child: () => mockLogger,
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+} as unknown as Logger
+
+describe("SpeechService direction resolution", () => {
+  describe("separateProviders = false (default)", () => {
+    it("uses shared apiKey for both STT and TTS", () => {
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          baseUrl: "https://api.openai.com/v1",
+          sttModel: "whisper-1",
+          ttsModel: "tts-1",
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.separateProviders, false)
+      assert.equal(caps.sttConfigured, true)
+      assert.equal(caps.ttsConfigured, true)
+      assert.equal(caps.configured, true)
+    })
+
+    it("reports unconfigured when no apiKey is set", () => {
+      const settings = createMockSettings({
+        speech: { sttModel: "whisper-1", ttsModel: "tts-1" },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttConfigured, false)
+      assert.equal(caps.ttsConfigured, false)
+      assert.equal(caps.configured, false)
+    })
+
+    it("transcribe throws not-configured when apiKey absent", async () => {
+      const service = new SpeechService(createMockSettings({ speech: {} }), mockLogger)
+      await assert.rejects(
+        () => service.transcribe({ audioBase64: "", mimeType: "audio/webm" }),
+        /not configured/i,
+      )
+    })
+  })
+
+  describe("separateProviders = true", () => {
+    it("reports per-direction configured status independently", () => {
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          separateProviders: true,
+          stt: { apiKey: "sk-groq", baseUrl: "https://api.groq.com/openai/v1", model: "whisper-large-v3" },
+          tts: { apiKey: "sk-openai", baseUrl: "https://api.openai.com/v1", model: "gpt-4o-mini-tts" },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.separateProviders, true)
+      assert.equal(caps.sttConfigured, true)
+      assert.equal(caps.ttsConfigured, true)
+      assert.equal(caps.configured, true)
+      assert.equal(caps.sttBaseUrl, "https://api.groq.com/openai/v1")
+      assert.equal(caps.ttsBaseUrl, "https://api.openai.com/v1")
+    })
+
+    it("reports partial config when only STT has complete directional pair", () => {
+      const settings = createMockSettings({
+        speech: {
+          separateProviders: true,
+          stt: { apiKey: "sk-groq", baseUrl: "https://api.groq.com/openai/v1" },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttConfigured, true)
+      assert.equal(caps.ttsConfigured, false)
+      assert.equal(caps.configured, false)
+    })
+
+    it("does NOT combine directional key with shared URL (incomplete pair)", () => {
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          baseUrl: "https://api.openai.com/v1",
+          separateProviders: true,
+          stt: { apiKey: "sk-groq" },
+          tts: { apiKey: "sk-deepseek" },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttConfigured, false, "directional key without directional URL should not be configured")
+      assert.equal(caps.ttsConfigured, false)
+    })
+
+    it("does NOT combine shared key with foreign directional URL (incomplete pair)", () => {
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          baseUrl: "https://api.openai.com/v1",
+          separateProviders: true,
+          stt: { baseUrl: "https://api.groq.com/openai/v1" },
+          tts: { baseUrl: "https://api.deepseek.com/v1" },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttConfigured, false)
+      assert.equal(caps.ttsConfigured, false)
+    })
+
+    it("treats directional baseUrl matching shared as inherited (no directional key)", () => {
+      const sharedUrl = "https://api.openai.com/v1"
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          baseUrl: sharedUrl,
+          separateProviders: true,
+          stt: { baseUrl: sharedUrl },
+          tts: { baseUrl: sharedUrl },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttConfigured, true, "directional baseUrl matching shared with no key should inherit shared key")
+      assert.equal(caps.ttsConfigured, true)
+    })
+
+    it("inherits complete shared pair when neither directional value is set", () => {
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          baseUrl: "https://api.openai.com/v1",
+          separateProviders: true,
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttConfigured, true)
+      assert.equal(caps.ttsConfigured, true)
+    })
+
+    it("uses complete directional pair when both key and URL are set", () => {
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          baseUrl: "https://api.openai.com/v1",
+          separateProviders: true,
+          stt: { apiKey: "sk-groq", baseUrl: "https://api.groq.com/openai/v1" },
+          tts: { apiKey: "sk-openai", baseUrl: "https://api.openai.com/v1" },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttConfigured, true)
+      assert.equal(caps.ttsConfigured, true)
+      assert.equal(caps.sttBaseUrl, "https://api.groq.com/openai/v1")
+    })
+
+    it("directional key with matching shared URL forms a complete pair", () => {
+      const sharedUrl = "https://api.openai.com/v1"
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          baseUrl: sharedUrl,
+          separateProviders: true,
+          stt: { apiKey: "sk-alt-openai", baseUrl: sharedUrl },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttConfigured, true, "directional key with matching shared URL should be a complete pair")
+    })
+
+    it("falls back to shared sttModel/ttsModel when per-direction model is absent", () => {
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          baseUrl: "https://api.openai.com/v1",
+          sttModel: "shared-stt-model",
+          ttsModel: "shared-tts-model",
+          separateProviders: true,
+          stt: { apiKey: "sk-stt", baseUrl: "https://api.openai.com/v1" },
+          tts: { apiKey: "sk-tts", baseUrl: "https://api.openai.com/v1" },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttModel, "shared-stt-model")
+      assert.equal(caps.ttsModel, "shared-tts-model")
+    })
+
+    it("uses per-direction model when set", () => {
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          baseUrl: "https://api.openai.com/v1",
+          sttModel: "shared-stt-model",
+          ttsModel: "shared-tts-model",
+          separateProviders: true,
+          stt: { apiKey: "sk-stt", baseUrl: "https://api.openai.com/v1", model: "whisper-large-v3" },
+          tts: { apiKey: "sk-tts", baseUrl: "https://api.openai.com/v1", model: "gpt-4o-mini-tts" },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttModel, "whisper-large-v3")
+      assert.equal(caps.ttsModel, "gpt-4o-mini-tts")
+    })
+
+    it("omits sttBaseUrl/ttsBaseUrl when separateProviders is false", () => {
+      const settings = createMockSettings({
+        speech: { apiKey: "sk-shared", baseUrl: "https://api.openai.com/v1" },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttBaseUrl, undefined)
+      assert.equal(caps.ttsBaseUrl, undefined)
+    })
+
+    it("transcribe throws not-configured for incomplete pair (key without URL)", async () => {
+      const settings = createMockSettings({
+        speech: {
+          apiKey: "sk-shared",
+          baseUrl: "https://api.openai.com/v1",
+          separateProviders: true,
+          stt: { apiKey: "sk-groq" },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      await assert.rejects(
+        () => service.transcribe({ audioBase64: "", mimeType: "audio/webm" }),
+        /not configured/i,
+      )
+    })
+
+    it("configured uses && in separate mode (both required for legacy compat)", () => {
+      const settings = createMockSettings({
+        speech: {
+          separateProviders: true,
+          stt: { apiKey: "sk-stt", baseUrl: "https://api.stt.com/v1" },
+        },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.sttConfigured, true)
+      assert.equal(caps.ttsConfigured, false)
+      assert.equal(caps.configured, false, "configured should be false when only one direction is ready")
+    })
+
+    it("configured uses || in shared mode", () => {
+      const settings = createMockSettings({
+        speech: { apiKey: "sk-shared", baseUrl: "https://api.openai.com/v1" },
+      })
+      const service = new SpeechService(settings, mockLogger)
+      const caps = service.getCapabilities()
+
+      assert.equal(caps.configured, true)
+    })
+  })
+})
diff --git a/packages/server/src/speech/service.ts b/packages/server/src/speech/service.ts
index d3c37646..e1fd9d82 100644
--- a/packages/server/src/speech/service.ts
+++ b/packages/server/src/speech/service.ts
@@ -15,6 +15,21 @@ const ServerSpeechSettingsSchema = z.object({
       ttsModel: z.string().optional(),
       ttsVoice: z.string().optional(),
       ttsFormat: z.enum(["mp3", "wav", "opus", "aac"]).optional(),
+      separateProviders: z.boolean().optional(),
+      stt: z
+        .object({
+          apiKey: z.string().nullish(),
+          baseUrl: z.string().nullish(),
+          model: z.string().nullish(),
+        })
+        .optional(),
+      tts: z
+        .object({
+          apiKey: z.string().nullish(),
+          baseUrl: z.string().nullish(),
+          model: z.string().nullish(),
+        })
+        .optional(),
     })
     .optional(),
 })
@@ -38,7 +53,10 @@ export interface SpeechSynthesisStreamResponse {
 }
 
 export interface SpeechProvider {
-  getCapabilities(): SpeechCapabilitiesResponse
+  getCapabilities(): Omit<
+    SpeechCapabilitiesResponse,
+    "separateProviders" | "sttConfigured" | "ttsConfigured" | "sttBaseUrl" | "ttsBaseUrl"
+  >
   transcribe(input: TranscribeAudioInput): Promise<SpeechTranscriptionResponse>
   synthesize(input: SynthesizeSpeechInput): Promise<SpeechSynthesisResponse>
   synthesizeStream(input: SynthesizeSpeechInput): Promise<SpeechSynthesisStreamResponse>
@@ -66,33 +84,76 @@ export class SpeechService {
   ) {}
 
   getCapabilities(): SpeechCapabilitiesResponse {
-    return this.createProvider().getCapabilities()
+    const parsed = this.parseConfig()
+    const speech = parsed.speech ?? {}
+    const separate = speech.separateProviders === true
+    const sttSettings = this.resolveSttSettingsFrom(speech)
+    const ttsSettings = this.resolveTtsSettingsFrom(speech)
+
+    const sttConfigured = Boolean(sttSettings.apiKey)
+    const ttsConfigured = Boolean(ttsSettings.apiKey)
+
+    return {
+      available: true,
+      configured: separate ? (sttConfigured && ttsConfigured) : (sttConfigured || ttsConfigured),
+      provider: sttSettings.provider,
+      supportsStt: true,
+      supportsTts: true,
+      supportsStreamingTts: true,
+      baseUrl: separate ? undefined : (speech.baseUrl?.trim() || process.env.OPENAI_BASE_URL || undefined),
+      sttModel: sttSettings.sttModel,
+      ttsModel: ttsSettings.ttsModel,
+      ttsVoice: ttsSettings.ttsVoice,
+      ttsFormats: ["mp3", "wav", "opus", "aac"],
+      streamingTtsFormats: ["mp3", "wav", "opus", "aac"],
+      separateProviders: separate,
+      sttConfigured,
+      ttsConfigured,
+      ...(separate ? { sttBaseUrl: sttSettings.baseUrl, ttsBaseUrl: ttsSettings.baseUrl } : {}),
+    }
   }
 
   async transcribe(input: TranscribeAudioInput): Promise<SpeechTranscriptionResponse> {
-    return this.createProvider().transcribe(input)
+    return this.createSttProvider().transcribe(input)
   }
 
   async synthesize(input: SynthesizeSpeechInput): Promise<SpeechSynthesisResponse> {
-    return this.createProvider().synthesize(input)
+    return this.createTtsProvider().synthesize(input)
   }
 
   async synthesizeStream(input: SynthesizeSpeechInput): Promise<SpeechSynthesisStreamResponse> {
-    return this.createProvider().synthesizeStream(input)
+    return this.createTtsProvider().synthesizeStream(input)
   }
 
-  private createProvider(): SpeechProvider {
-    const settings = this.resolveSettings()
+  private parseConfig() {
+    return ServerSpeechSettingsSchema.parse(this.settings.getOwner("config", "server") ?? {})
+  }
+
+  private createSttProvider(): SpeechProvider {
+    const settings = this.resolveSttSettings()
     return new OpenAICompatibleSpeechProvider({
       settings,
-      logger: this.logger.child({ provider: settings.provider }),
+      logger: this.logger.child({ provider: settings.provider, direction: "stt" }),
     })
   }
 
-  private resolveSettings(): NormalizedSpeechSettings {
-    const parsed = ServerSpeechSettingsSchema.parse(this.settings.getOwner("config", "server") ?? {})
-    const speech = parsed.speech ?? {}
+  private createTtsProvider(): SpeechProvider {
+    const settings = this.resolveTtsSettings()
+    return new OpenAICompatibleSpeechProvider({
+      settings,
+      logger: this.logger.child({ provider: settings.provider, direction: "tts" }),
+    })
+  }
 
+  private resolveSttSettings(): NormalizedSpeechSettings {
+    return this.resolveSttSettingsFrom(this.parseConfig().speech ?? {})
+  }
+
+  private resolveTtsSettings(): NormalizedSpeechSettings {
+    return this.resolveTtsSettingsFrom(this.parseConfig().speech ?? {})
+  }
+
+  private resolveShared(speech: NonNullable<z.infer<typeof ServerSpeechSettingsSchema>["speech"]>): NormalizedSpeechSettings {
     return {
       provider: speech.provider?.trim() || DEFAULT_PROVIDER,
       apiKey: speech.apiKey?.trim() || process.env.OPENAI_API_KEY,
@@ -103,4 +164,64 @@ export class SpeechService {
       ttsFormat: speech.ttsFormat ?? DEFAULT_TTS_FORMAT,
     }
   }
+
+  private resolveSttSettingsFrom(speech: NonNullable<z.infer<typeof ServerSpeechSettingsSchema>["speech"]>): NormalizedSpeechSettings {
+    if (speech.separateProviders !== true) {
+      return this.resolveShared(speech)
+    }
+    const stt = speech.stt ?? {}
+    const sharedBaseUrl = speech.baseUrl?.trim() || undefined
+    const rawDirBaseUrl = stt.baseUrl?.trim() || undefined
+    const dirApiKey = stt.apiKey?.trim() || undefined
+    const dirBaseUrl = dirApiKey
+      ? rawDirBaseUrl
+      : (rawDirBaseUrl && rawDirBaseUrl !== sharedBaseUrl ? rawDirBaseUrl : undefined)
+    const hasCompleteDirectional = Boolean(dirApiKey) && Boolean(dirBaseUrl)
+    const hasNoDirectional = !dirApiKey && !dirBaseUrl
+    return {
+      provider: speech.provider?.trim() || DEFAULT_PROVIDER,
+      apiKey: hasCompleteDirectional
+        ? dirApiKey
+        : hasNoDirectional
+          ? speech.apiKey?.trim() || process.env.OPENAI_API_KEY
+          : undefined,
+      baseUrl: hasCompleteDirectional || hasNoDirectional
+        ? (dirBaseUrl || sharedBaseUrl || process.env.OPENAI_BASE_URL || undefined)
+        : dirBaseUrl || undefined,
+      sttModel: stt.model?.trim() || speech.sttModel?.trim() || DEFAULT_STT_MODEL,
+      ttsModel: speech.ttsModel?.trim() || DEFAULT_TTS_MODEL,
+      ttsVoice: speech.ttsVoice?.trim() || DEFAULT_TTS_VOICE,
+      ttsFormat: speech.ttsFormat ?? DEFAULT_TTS_FORMAT,
+    }
+  }
+
+  private resolveTtsSettingsFrom(speech: NonNullable<z.infer<typeof ServerSpeechSettingsSchema>["speech"]>): NormalizedSpeechSettings {
+    if (speech.separateProviders !== true) {
+      return this.resolveShared(speech)
+    }
+    const tts = speech.tts ?? {}
+    const sharedBaseUrl = speech.baseUrl?.trim() || undefined
+    const rawDirBaseUrl = tts.baseUrl?.trim() || undefined
+    const dirApiKey = tts.apiKey?.trim() || undefined
+    const dirBaseUrl = dirApiKey
+      ? rawDirBaseUrl
+      : (rawDirBaseUrl && rawDirBaseUrl !== sharedBaseUrl ? rawDirBaseUrl : undefined)
+    const hasCompleteDirectional = Boolean(dirApiKey) && Boolean(dirBaseUrl)
+    const hasNoDirectional = !dirApiKey && !dirBaseUrl
+    return {
+      provider: speech.provider?.trim() || DEFAULT_PROVIDER,
+      apiKey: hasCompleteDirectional
+        ? dirApiKey
+        : hasNoDirectional
+          ? speech.apiKey?.trim() || process.env.OPENAI_API_KEY
+          : undefined,
+      baseUrl: hasCompleteDirectional || hasNoDirectional
+        ? (dirBaseUrl || sharedBaseUrl || process.env.OPENAI_BASE_URL || undefined)
+        : dirBaseUrl || undefined,
+      sttModel: speech.sttModel?.trim() || DEFAULT_STT_MODEL,
+      ttsModel: tts.model?.trim() || speech.ttsModel?.trim() || DEFAULT_TTS_MODEL,
+      ttsVoice: speech.ttsVoice?.trim() || DEFAULT_TTS_VOICE,
+      ttsFormat: speech.ttsFormat ?? DEFAULT_TTS_FORMAT,
+    }
+  }
 }
diff --git a/packages/server/src/usage/providers/api-key.ts b/packages/server/src/usage/providers/api-key.ts
new file mode 100644
index 00000000..756e25f1
--- /dev/null
+++ b/packages/server/src/usage/providers/api-key.ts
@@ -0,0 +1,182 @@
+import type { UsageProvider } from "../types"
+import {
+  fetchJson,
+  getCredential,
+  notConfigured,
+  resolveWindowLabel,
+  safeFetch,
+  toNumber,
+  toTimestamp,
+  toUsageWindow,
+} from "../shared"
+
+const kimiAliases = ["kimi-for-coding", "kimi"] as const
+const kimi: UsageProvider = {
+  id: "kimi-for-coding",
+  name: "Kimi for Coding",
+  aliases: kimiAliases,
+  async fetchQuota() {
+    const key = getCredential(kimiAliases, ["key", "token"])
+    if (!key) return notConfigured(this.id, this.name)
+    return safeFetch(this.id, this.name, async () => {
+      const payload = await fetchJson("https://api.kimi.com/coding/v1/usages", {
+        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      })
+      const windows: Record<string, ReturnType<typeof toUsageWindow>> = {}
+      const usage = payload?.usage
+      if (usage) {
+        const limit = toNumber(usage.limit)
+        const remaining = toNumber(usage.remaining)
+        windows.weekly = toUsageWindow({
+          usedPercent: limit && remaining !== null ? 100 - (remaining / limit) * 100 : null,
+          resetAt: toTimestamp(usage.resetTime),
+        })
+      }
+      for (const item of Array.isArray(payload?.limits) ? payload.limits : []) {
+        const duration = toNumber(item?.window?.duration)
+        const unit = item?.window?.timeUnit
+        const multiplier = unit === "TIME_UNIT_MINUTE" ? 60 : unit === "TIME_UNIT_HOUR" ? 3600 : unit === "TIME_UNIT_DAY" ? 86_400 : null
+        const seconds = duration !== null && multiplier ? duration * multiplier : null
+        const limit = toNumber(item?.detail?.limit)
+        const remaining = toNumber(item?.detail?.remaining)
+        windows[resolveWindowLabel(seconds)] = toUsageWindow({
+          usedPercent: limit && remaining !== null ? 100 - (remaining / limit) * 100 : null,
+          windowSeconds: seconds,
+          resetAt: toTimestamp(item?.detail?.resetTime),
+        })
+      }
+      return { windows }
+    })
+  },
+}
+
+const nanoAliases = ["nano-gpt", "nanogpt", "nano_gpt"] as const
+const nanoGpt: UsageProvider = {
+  id: "nano-gpt",
+  name: "NanoGPT",
+  aliases: nanoAliases,
+  async fetchQuota() {
+    const key = getCredential(nanoAliases, ["key", "token"])
+    if (!key) return notConfigured(this.id, this.name)
+    return safeFetch(this.id, this.name, async () => {
+      const payload = await fetchJson("https://nano-gpt.com/api/subscription/v1/usage", {
+        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      })
+      const windows: Record<string, ReturnType<typeof toUsageWindow>> = {}
+      for (const [label, source] of [["daily", payload?.daily], ["monthly", payload?.monthly]] as const) {
+        if (!source) continue
+        const fraction = toNumber(source.percentUsed)
+        const used = toNumber(source.used)
+        const limit = toNumber(source.limit ?? source.limits?.[label])
+        windows[label] = toUsageWindow({
+          usedPercent: fraction !== null ? fraction * 100 : used !== null && limit ? (used / limit) * 100 : null,
+          windowSeconds: label === "daily" ? 86_400 : null,
+          resetAt: toTimestamp(source.resetAt ?? payload?.period?.currentPeriodEnd),
+        })
+      }
+      return { windows }
+    })
+  },
+}
+
+const openRouterAliases = ["openrouter"] as const
+const openRouter: UsageProvider = {
+  id: "openrouter",
+  name: "OpenRouter",
+  aliases: openRouterAliases,
+  async fetchQuota() {
+    const key = getCredential(openRouterAliases, ["key", "token"])
+    if (!key) return notConfigured(this.id, this.name)
+    return safeFetch(this.id, this.name, async () => {
+      const payload = await fetchJson("https://openrouter.ai/api/v1/credits", {
+        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      })
+      const total = toNumber(payload?.data?.total_credits)
+      const used = toNumber(payload?.data?.total_usage)
+      const remaining = total !== null && used !== null ? Math.max(0, total - used) : null
+      return {
+        windows: {
+          credits: toUsageWindow({
+            usedPercent: total && used !== null ? (used / total) * 100 : null,
+            valueLabel: remaining !== null && total !== null ? `$${remaining.toFixed(2)} / $${total.toFixed(2)}` : null,
+          }),
+        },
+      }
+    })
+  },
+}
+
+function createTokenLimitProvider(input: { id: string; name: string; aliases: readonly string[]; url: string }): UsageProvider {
+  return {
+    id: input.id,
+    name: input.name,
+    aliases: input.aliases,
+    async fetchQuota() {
+      const key = getCredential(input.aliases, ["key", "token"])
+      if (!key) return notConfigured(this.id, this.name)
+      return safeFetch(this.id, this.name, async () => {
+        const payload = await fetchJson(input.url, { headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" } })
+        const windows: Record<string, ReturnType<typeof toUsageWindow>> = {}
+        for (const limit of Array.isArray(payload?.data?.limits) ? payload.data.limits : []) {
+          if (limit?.type !== "TOKENS_LIMIT" && limit?.type !== "TIME_LIMIT") continue
+          const duration = toNumber(limit.number)
+          const seconds = limit.type === "TIME_LIMIT" ? 30 * 86_400 : limit.unit === 3 && duration ? duration * 3600 : null
+          const label = limit.type === "TIME_LIMIT" ? "mcp-tools" : resolveWindowLabel(seconds)
+          windows[label] = toUsageWindow({
+            usedPercent: toNumber(limit.percentage),
+            windowSeconds: seconds,
+            resetAt: toTimestamp(limit.nextResetTime),
+          })
+        }
+        return { windows }
+      })
+    },
+  }
+}
+
+const zai = createTokenLimitProvider({
+  id: "zai-coding-plan",
+  name: "z.ai",
+  aliases: ["zai-coding-plan", "zai", "z.ai"],
+  url: "https://api.z.ai/api/monitor/usage/quota/limit",
+})
+
+const zhipu = createTokenLimitProvider({
+  id: "zhipuai-coding-plan",
+  name: "Zhipu AI Coding Plan",
+  aliases: ["zhipuai-coding-plan", "zhipuai", "zhipu"],
+  url: "https://open.bigmodel.cn/api/monitor/usage/quota/limit",
+})
+
+const waferAliases = ["wafer", "wafer-ai", "wafer_ai", "wafer.ai"] as const
+const wafer: UsageProvider = {
+  id: "wafer",
+  name: "Wafer.ai",
+  aliases: waferAliases,
+  async fetchQuota() {
+    const key = getCredential(waferAliases, ["key", "token"])
+    if (!key) return notConfigured(this.id, this.name)
+    return safeFetch(this.id, this.name, async () => {
+      const payload = await fetchJson("https://pass.wafer.ai/v1/inference/quota", {
+        headers: { Authorization: `Bearer ${key}`, "Accept-Encoding": "identity" },
+      })
+      const remaining = toNumber(payload?.remaining_included_requests)
+      const limit = toNumber(payload?.included_request_limit)
+      const startAt = toTimestamp(payload?.window_start)
+      const resetAt = toTimestamp(payload?.window_end)
+      const seconds = startAt !== null && resetAt !== null ? Math.round((resetAt - startAt) / 1000) : 5 * 3600
+      return {
+        windows: {
+          [resolveWindowLabel(seconds)]: toUsageWindow({
+            usedPercent: toNumber(payload?.current_period_used_percent),
+            windowSeconds: seconds,
+            resetAt,
+            valueLabel: remaining !== null && limit !== null ? `${remaining} / ${limit}` : null,
+          }),
+        },
+      }
+    })
+  },
+}
+
+export const apiKeyProviders: UsageProvider[] = [kimi, nanoGpt, openRouter, zai, zhipu, wafer]
diff --git a/packages/server/src/usage/providers/google.ts b/packages/server/src/usage/providers/google.ts
new file mode 100644
index 00000000..f624b7e7
--- /dev/null
+++ b/packages/server/src/usage/providers/google.ts
@@ -0,0 +1,179 @@
+import fs from "fs"
+import os from "os"
+import path from "path"
+
+import type { UsageProvider } from "../types"
+import { asObject, fetchJson, getAuthEntry, getString, notConfigured, result, toNumber, toTimestamp, toUsageWindow } from "../shared"
+
+const GOOGLE_ENDPOINTS = [
+  "https://daily-cloudcode-pa.sandbox.googleapis.com",
+  "https://autopush-cloudcode-pa.sandbox.googleapis.com",
+  "https://cloudcode-pa.googleapis.com",
+] as const
+const DEFAULT_PROJECT_ID = "rising-fact-p41fc"
+
+interface GoogleSource {
+  id: "gemini" | "antigravity"
+  accessToken?: string
+  refreshToken?: string
+  projectId?: string
+  expires?: number | null
+}
+
+function parseRefresh(value: unknown): { token?: string; projectId?: string } {
+  const raw = getString(value)
+  if (!raw) return {}
+  const [token, projectId, managedProjectId] = raw.split("|")
+  return { token: getString(token) ?? undefined, projectId: getString(projectId) ?? getString(managedProjectId) ?? undefined }
+}
+
+function readJson(filePath: string): any | null {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"))
+  } catch {
+    return null
+  }
+}
+
+function googleSources(): GoogleSource[] {
+  const sources: GoogleSource[] = []
+  const entry = asObject(getAuthEntry(["google", "google.oauth"]))
+  const oauth = asObject(entry?.oauth) ?? entry
+  if (oauth) {
+    const refresh = parseRefresh(oauth.refresh)
+    const accessToken = getString(oauth.access) ?? getString(oauth.token) ?? undefined
+    if (accessToken || refresh.token) {
+      sources.push({
+        id: "gemini",
+        accessToken,
+        refreshToken: refresh.token,
+        projectId: refresh.projectId,
+        expires: toTimestamp(oauth.expires),
+      })
+    }
+  }
+
+  const home = os.homedir()
+  for (const candidate of [
+    path.join(home, ".config", "opencode", "antigravity-accounts.json"),
+    path.join(home, ".local", "share", "opencode", "antigravity-accounts.json"),
+  ]) {
+    const data = readJson(candidate)
+    const accounts = Array.isArray(data?.accounts) ? data.accounts : []
+    const account = accounts[data?.activeIndex ?? 0] ?? accounts[0]
+    const refresh = parseRefresh(account?.refreshToken)
+    const accessToken = getString(account?.accessToken) ?? getString(account?.access_token) ?? undefined
+    if (accessToken || refresh.token) {
+      sources.push({
+        id: "antigravity",
+        accessToken,
+        refreshToken: refresh.token,
+        projectId: getString(account?.projectId) ?? refresh.projectId,
+        expires: toTimestamp(account?.expiresAt ?? account?.expires),
+      })
+      break
+    }
+  }
+  return sources
+}
+
+async function refreshAccessToken(source: GoogleSource): Promise<string | null> {
+  if (!source.refreshToken) return null
+  const prefix = source.id === "gemini" ? "GOOGLE" : "ANTIGRAVITY"
+  const clientId = getString(process.env[`${prefix}_OAUTH_CLIENT_ID`])
+  const clientSecret = getString(process.env[`${prefix}_OAUTH_CLIENT_SECRET`])
+  if (!clientId || !clientSecret) return null
+  const payload = await fetchJson("https://oauth2.googleapis.com/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: clientId,
+      client_secret: clientSecret,
+      refresh_token: source.refreshToken,
+      grant_type: "refresh_token",
+    }),
+  })
+  return getString(payload?.access_token)
+}
+
+function transformModel(sourceId: string, modelId: string, data: any) {
+  const fraction = toNumber(data?.quotaInfo?.remainingFraction ?? data?.remainingFraction)
+  const resetAt = toTimestamp(data?.quotaInfo?.resetTime ?? data?.resetTime)
+  const label = sourceId === "gemini" || (resetAt !== null && resetAt - Date.now() > 10 * 3600 * 1000) ? "daily" : "5h"
+  return {
+    [`${sourceId}/${modelId}`]: {
+      windows: {
+        [label]: toUsageWindow({
+          usedPercent: fraction === null ? null : 100 - fraction * 100,
+          windowSeconds: label === "daily" ? 86_400 : 5 * 3600,
+          resetAt,
+        }),
+      },
+    },
+  }
+}
+
+const google: UsageProvider = {
+  id: "google",
+  name: "Google",
+  aliases: ["google", "google.oauth", "gemini", "antigravity"],
+  async fetchQuota() {
+    const sources = googleSources()
+    if (sources.length === 0) return notConfigured(this.id, this.name)
+    const models: Record<string, { windows: Record<string, ReturnType<typeof toUsageWindow>> }> = {}
+    try {
+      for (const source of sources) {
+        const accessToken = source.accessToken && (!source.expires || source.expires > Date.now())
+          ? source.accessToken
+          : await refreshAccessToken(source)
+        if (!accessToken) continue
+        const projectId = source.projectId ?? DEFAULT_PROJECT_ID
+        if (source.id === "gemini") {
+          try {
+            const quota = await fetchJson(`${GOOGLE_ENDPOINTS[2]}/v1internal:retrieveUserQuota`, {
+              method: "POST",
+              headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+              body: JSON.stringify({ project: projectId }),
+            })
+            for (const bucket of Array.isArray(quota?.buckets) ? quota.buckets : []) {
+              const modelId = getString(bucket?.modelId)
+              if (modelId) Object.assign(models, transformModel(source.id, modelId, bucket))
+            }
+          } catch {
+            // The model endpoint below often remains available when quota buckets are not.
+          }
+        }
+        for (const endpoint of GOOGLE_ENDPOINTS) {
+          try {
+            const payload = await fetchJson(`${endpoint}/v1internal:fetchAvailableModels`, {
+              method: "POST",
+              headers: {
+                Authorization: `Bearer ${accessToken}`,
+                "Content-Type": "application/json",
+                "User-Agent": "antigravity/1.11.5 windows/amd64",
+                "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+              },
+              body: JSON.stringify({ project: projectId }),
+            })
+            for (const [modelId, data] of Object.entries(payload?.models ?? {})) {
+              Object.assign(models, transformModel(source.id, modelId, data))
+            }
+            break
+          } catch {
+            continue
+          }
+        }
+      }
+      if (Object.keys(models).length === 0) throw new Error("No model quota data available")
+      return result(this.id, this.name, { ok: true, configured: true, usage: { windows: {}, models } })
+    } catch (error) {
+      return result(this.id, this.name, {
+        ok: false,
+        configured: true,
+        error: error instanceof Error ? error.message : "Request failed",
+      })
+    }
+  },
+}
+
+export const googleProviders: UsageProvider[] = [google]
diff --git a/packages/server/src/usage/providers/minimax.ts b/packages/server/src/usage/providers/minimax.ts
new file mode 100644
index 00000000..dd24d9f9
--- /dev/null
+++ b/packages/server/src/usage/providers/minimax.ts
@@ -0,0 +1,116 @@
+import type { UsageProvider } from "../types"
+import { fetchJson, getCredential, notConfigured, result, toNumber, toTimestamp, toUsageWindow } from "../shared"
+
+const INACTIVE_WINDOW_STATUS = 3
+
+function pickChatModel(models: any[]): any | null {
+  return (
+    models.find((model) => /^minimax-m/i.test(String(model?.model_name ?? "")) && (toNumber(model?.current_interval_total_count) ?? 0) > 0) ??
+    models.find((model) => ["general", "chat", "text"].includes(String(model?.model_name ?? "").toLowerCase())) ??
+    models.find((model) => toNumber(model?.current_interval_remaining_percent) !== null) ??
+    models[0] ??
+    null
+  )
+}
+
+function isUsablePayload(payload: any): boolean {
+  if (payload?.base_resp && payload.base_resp.status_code !== 0) return false
+  return Array.isArray(payload?.model_remains) && payload.model_remains.length > 0
+}
+
+function usedPercent(model: any, prefix: "interval" | "weekly", tokenPlan: boolean): number | null {
+  const remainingPercent = toNumber(model?.[`current_${prefix}_remaining_percent`])
+  if (remainingPercent !== null) return 100 - remainingPercent
+  const total = toNumber(model?.[`current_${prefix}_total_count`])
+  const rawUsage = toNumber(model?.[`current_${prefix}_usage_count`])
+  if (!total || rawUsage === null) return null
+  const used = tokenPlan ? total - rawUsage : rawUsage
+  return (Math.max(0, used) / total) * 100
+}
+
+function windowSeconds(model: any, prefix: "interval" | "weekly"): number | null {
+  const startAt = toTimestamp(prefix === "interval" ? model?.start_time : model?.weekly_start_time)
+  const resetAt = toTimestamp(prefix === "interval" ? model?.end_time : model?.weekly_end_time)
+  if (startAt !== null && resetAt !== null && resetAt > startAt) return Math.floor((resetAt - startAt) / 1000)
+  const remainsMs = toNumber(prefix === "interval" ? model?.remains_time : model?.weekly_remains_time)
+  return remainsMs && remainsMs > 0 ? Math.floor(remainsMs / 1000) : null
+}
+
+function createMiniMaxProvider(input: {
+  id: string
+  name: string
+  aliases: readonly string[]
+  tokenPlanUrl: string
+  codingPlanUrl: string
+}): UsageProvider {
+  return {
+    id: input.id,
+    name: input.name,
+    aliases: input.aliases,
+    async fetchQuota() {
+      const key = getCredential(input.aliases, ["key", "token"])
+      if (!key) return notConfigured(this.id, this.name)
+      try {
+        let tokenPlan = true
+        let payload: any = null
+        try {
+          const tokenPayload = await fetchJson(input.tokenPlanUrl, { headers: { Authorization: `Bearer ${key}` } })
+          if (isUsablePayload(tokenPayload)) payload = tokenPayload
+        } catch {
+          // Fall back to the legacy Coding Plan endpoint below.
+        }
+        if (!payload) {
+          tokenPlan = false
+          const codingPayload = await fetchJson(input.codingPlanUrl, { headers: { Authorization: `Bearer ${key}` } })
+          if (isUsablePayload(codingPayload)) payload = codingPayload
+        }
+        if (!payload) throw new Error("Provider returned no usable quota data")
+        const model = pickChatModel(Array.isArray(payload?.model_remains) ? payload.model_remains : [])
+        if (!model) throw new Error("No model quota data available")
+        const intervalResetAt = toTimestamp(model?.end_time)
+        const windows: Record<string, ReturnType<typeof toUsageWindow>> = {
+          "5h": toUsageWindow({
+            usedPercent: usedPercent(model, "interval", tokenPlan),
+            windowSeconds: windowSeconds(model, "interval"),
+            resetAt: intervalResetAt,
+          }),
+        }
+        const weeklyStatus = toNumber(model?.current_weekly_status)
+        const hasWeekly = weeklyStatus !== INACTIVE_WINDOW_STATUS && (
+          toNumber(model?.current_weekly_remaining_percent) !== null || (toNumber(model?.current_weekly_total_count) ?? 0) > 0
+        )
+        if (hasWeekly) {
+          windows.weekly = toUsageWindow({
+            usedPercent: usedPercent(model, "weekly", tokenPlan),
+            windowSeconds: windowSeconds(model, "weekly"),
+            resetAt: toTimestamp(model?.weekly_end_time),
+          })
+        }
+        return result(this.id, this.name, { ok: true, configured: true, usage: { windows } })
+      } catch (error) {
+        return result(this.id, this.name, {
+          ok: false,
+          configured: true,
+          error: error instanceof Error ? error.message : "Request failed",
+        })
+      }
+    },
+  }
+}
+
+export const miniMaxProviders: UsageProvider[] = [
+  createMiniMaxProvider({
+    id: "minimax-coding-plan",
+    name: "MiniMax Coding Plan",
+    aliases: ["minimax-coding-plan", "minimax"],
+    tokenPlanUrl: "https://api.minimax.io/v1/token_plan/remains",
+    codingPlanUrl: "https://api.minimax.io/v1/api/openplatform/coding_plan/remains",
+  }),
+  createMiniMaxProvider({
+    id: "minimax-cn-coding-plan",
+    name: "MiniMax Coding Plan CN",
+    aliases: ["minimax-cn-coding-plan", "minimaxi"],
+    tokenPlanUrl: "https://api.minimaxi.com/v1/token_plan/remains",
+    codingPlanUrl: "https://www.minimaxi.com/v1/api/openplatform/coding_plan/remains",
+  }),
+]
diff --git a/packages/server/src/usage/providers/oauth.ts b/packages/server/src/usage/providers/oauth.ts
new file mode 100644
index 00000000..8b64473e
--- /dev/null
+++ b/packages/server/src/usage/providers/oauth.ts
@@ -0,0 +1,86 @@
+import type { UsageProvider } from "../types"
+import {
+  fetchJson,
+  getAuthEntry,
+  getCredential,
+  notConfigured,
+  resolveWindowLabel,
+  safeFetch,
+  toNumber,
+  toTimestamp,
+  toUsageWindow,
+} from "../shared"
+
+const codexAliases = ["openai", "codex", "chatgpt"] as const
+const codex: UsageProvider = {
+  id: "codex",
+  name: "Codex",
+  aliases: codexAliases,
+  async fetchQuota() {
+    const entry = getAuthEntry(codexAliases)
+    const token = entry && (typeof entry.access === "string" ? entry.access : typeof entry.token === "string" ? entry.token : null)
+    if (!token) return notConfigured(this.id, this.name)
+    return safeFetch(this.id, this.name, async () => {
+      const accountId = typeof entry?.accountId === "string" ? entry.accountId : null
+      const payload = await fetchJson("https://chatgpt.com/backend-api/wham/usage", {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          ...(accountId ? { "ChatGPT-Account-Id": accountId } : {}),
+        },
+      })
+      const windows: Record<string, ReturnType<typeof toUsageWindow>> = {}
+      for (const source of [payload?.rate_limit?.primary_window, payload?.rate_limit?.secondary_window]) {
+        if (!source) continue
+        const seconds = toNumber(source.limit_window_seconds)
+        windows[resolveWindowLabel(seconds)] = toUsageWindow({
+          usedPercent: toNumber(source.used_percent),
+          windowSeconds: seconds,
+          resetAt: toTimestamp(source.reset_at),
+        })
+      }
+      return { windows }
+    })
+  },
+}
+
+const copilotAliases = ["github-copilot", "copilot"] as const
+const copilot: UsageProvider = {
+  id: "github-copilot",
+  name: "GitHub Copilot",
+  aliases: copilotAliases,
+  async fetchQuota() {
+    const token = getCredential(copilotAliases, ["access", "token"])
+    if (!token) return notConfigured(this.id, this.name)
+    return safeFetch(this.id, this.name, async () => {
+      const payload = await fetchJson("https://api.github.com/copilot_internal/user", {
+        headers: {
+          Authorization: `token ${token}`,
+          Accept: "application/json",
+          "Editor-Version": "vscode/1.96.2",
+          "X-Github-Api-Version": "2025-04-01",
+        },
+      })
+      const resetAt = toTimestamp(payload?.quota_reset_date)
+      const windows: Record<string, ReturnType<typeof toUsageWindow>> = {}
+      for (const [key, snapshot] of Object.entries({
+        chat: payload?.quota_snapshots?.chat,
+        completions: payload?.quota_snapshots?.completions,
+        premium: payload?.quota_snapshots?.premium_interactions,
+      })) {
+        if (!snapshot) continue
+        const source = snapshot as Record<string, unknown>
+        const entitlement = toNumber(source.entitlement)
+        const remaining = toNumber(source.remaining)
+        windows[key] = toUsageWindow({
+          usedPercent: entitlement && remaining !== null ? 100 - (remaining / entitlement) * 100 : null,
+          resetAt,
+          valueLabel: entitlement !== null && remaining !== null ? `${remaining.toFixed(0)} / ${entitlement.toFixed(0)}` : null,
+        })
+      }
+      return { windows }
+    })
+  },
+}
+
+export const oauthProviders: UsageProvider[] = [codex, copilot]
diff --git a/packages/server/src/usage/providers/special.ts b/packages/server/src/usage/providers/special.ts
new file mode 100644
index 00000000..33e056d8
--- /dev/null
+++ b/packages/server/src/usage/providers/special.ts
@@ -0,0 +1,145 @@
+import type { UsageProvider } from "../types"
+import { fetchJson, getString, notConfigured, safeFetch, toNumber, toTimestamp, toUsageWindow } from "../shared"
+
+function decodeJwtExpiration(token: string): number | null {
+  try {
+    const payload = token.split(".")[1]
+    if (!payload) return null
+    const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"))
+    return typeof parsed?.exp === "number" ? parsed.exp * 1000 : null
+  } catch {
+    return null
+  }
+}
+
+async function resolveCursorToken(): Promise<string | null> {
+  const accessToken = getString(process.env.CURSOR_ACCESS_TOKEN) ?? getString(process.env.CURSOR_TOKEN)
+  const refreshToken = getString(process.env.CURSOR_REFRESH_TOKEN)
+  const expiresAt = accessToken ? decodeJwtExpiration(accessToken) : null
+  if (accessToken && (!expiresAt || expiresAt > Date.now() + 5 * 60_000)) return accessToken
+  if (!refreshToken) return accessToken
+  const payload = await fetchJson("https://api2.cursor.sh/oauth/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ grant_type: "refresh_token", client_id: "KbZUR41cY7W6zRSdpSUJ7I7mLYBKOCmB", refresh_token: refreshToken }),
+  })
+  return getString(payload?.access_token)
+}
+
+async function cursorPost(url: string, token: string): Promise<any> {
+  return fetchJson(url, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "Connect-Protocol-Version": "1" },
+    body: "{}",
+  })
+}
+
+const cursor: UsageProvider = {
+  id: "cursor",
+  name: "Cursor",
+  aliases: ["cursor"],
+  async fetchQuota() {
+    const token = await resolveCursorToken().catch(() => null)
+    if (!token) return notConfigured(this.id, this.name)
+    return safeFetch(this.id, this.name, async () => {
+      const usage = await cursorPost("https://api2.cursor.sh/aiserver.v1.DashboardService/GetCurrentPeriodUsage", token)
+      const plan = await cursorPost("https://api2.cursor.sh/aiserver.v1.DashboardService/GetPlanInfo", token).catch(() => null)
+      const source = usage?.planUsage ?? {}
+      const limit = toNumber(source.limit)
+      const remaining = toNumber(source.remaining)
+      const explicit = toNumber(source.totalPercentUsed)
+      const resetAt = toTimestamp(usage?.billingCycleEnd ?? plan?.planInfo?.billingCycleEnd)
+      return {
+        windows: {
+          billing_cycle: toUsageWindow({
+            usedPercent: explicit ?? (limit && remaining !== null ? ((limit - remaining) / limit) * 100 : null),
+            resetAt,
+            valueLabel: toNumber(source.totalSpend) !== null ? `$${(toNumber(source.totalSpend)! / 100).toFixed(2)}` : null,
+          }),
+        },
+      }
+    })
+  },
+}
+
+function parseOllamaUsage(html: string) {
+  const windows: Record<string, ReturnType<typeof toUsageWindow>> = {}
+  for (const [label, pattern] of [
+    ["session", /Session\s+usage[^0-9]*([0-9.]+)%/i],
+    ["weekly", /Weekly\s+usage[^0-9]*([0-9.]+)%/i],
+  ] as const) {
+    const match = html.match(pattern)
+    if (match) windows[label] = toUsageWindow({ usedPercent: toNumber(match[1]) })
+  }
+  const premium = html.match(/Premium[^0-9]*([0-9]+)\s*\/\s*([0-9]+)/i)
+  if (premium) {
+    const used = toNumber(premium[1])
+    const total = toNumber(premium[2])
+    windows.premium = toUsageWindow({
+      usedPercent: total && used !== null ? (used / total) * 100 : null,
+      valueLabel: used !== null && total !== null ? `${used} / ${total}` : null,
+    })
+  }
+  return windows
+}
+
+const ollamaCloud: UsageProvider = {
+  id: "ollama-cloud",
+  name: "Ollama Cloud",
+  aliases: ["ollama-cloud", "ollamacloud"],
+  async fetchQuota() {
+    const cookie = getString(process.env.OLLAMA_CLOUD_COOKIE)
+    if (!cookie) return notConfigured(this.id, this.name)
+    return safeFetch(this.id, this.name, async () => {
+      const response = await fetch("https://ollama.com/settings", {
+        headers: { Cookie: cookie, "User-Agent": "CodeNomad usage provider" },
+        redirect: "manual",
+        signal: AbortSignal.timeout(15_000),
+      })
+      if (!response.ok) throw new Error(`Provider returned HTTP ${response.status}`)
+      const windows = parseOllamaUsage(await response.text())
+      if (Object.keys(windows).length === 0) throw new Error("No usage data available")
+      return { windows }
+    })
+  },
+}
+
+function parseOpenCodeGoUsage(html: string, now = Date.now()) {
+  const normalized = html.replace(/&quot;|&#34;|\\u0022|\\"/g, '"')
+  const windows: Record<string, ReturnType<typeof toUsageWindow>> = {}
+  for (const [label, field] of Object.entries({ "5h": "rollingUsage", weekly: "weeklyUsage", monthly: "monthlyUsage" })) {
+    const match = normalized.match(new RegExp(`["']?${field}["']?\\s*:\\s*(?:\\$R\\[\\d+\\]\\s*=\\s*)?\\{([^{}]*)\\}`, "s"))
+    if (!match) continue
+    const capture = (name: string) => toNumber(match[1]?.match(new RegExp(`["']?${name}["']?\\s*:\\s*["']?(-?\\d+(?:\\.\\d+)?)`))?.[1])
+    const usedPercent = capture("usagePercent")
+    const resetInSec = capture("resetInSec")
+    if (usedPercent !== null && resetInSec !== null) {
+      windows[label] = toUsageWindow({ usedPercent, resetAt: now + Math.max(0, resetInSec) * 1000 })
+    }
+  }
+  return windows
+}
+
+const openCodeGo: UsageProvider = {
+  id: "opencode-go",
+  name: "OpenCode Go",
+  aliases: ["opencode-go", "opencode"],
+  async fetchQuota() {
+    const workspaceId = getString(process.env.OPENCODE_GO_WORKSPACE_ID)
+    const authCookie = getString(process.env.OPENCODE_GO_AUTH_COOKIE)
+    if (!workspaceId || !authCookie) return notConfigured(this.id, this.name)
+    return safeFetch(this.id, this.name, async () => {
+      const response = await fetch(`https://opencode.ai/workspace/${encodeURIComponent(workspaceId)}/go`, {
+        headers: { Cookie: `auth=${authCookie.replace(/^auth=/, "")}`, "User-Agent": "CodeNomad usage provider" },
+        redirect: "manual",
+        signal: AbortSignal.timeout(15_000),
+      })
+      if (!response.ok) throw new Error(`Provider returned HTTP ${response.status}`)
+      const windows = parseOpenCodeGoUsage(await response.text())
+      if (Object.keys(windows).length === 0) throw new Error("No usage data available")
+      return { windows }
+    })
+  },
+}
+
+export const specialProviders: UsageProvider[] = [cursor, ollamaCloud, openCodeGo]
diff --git a/packages/server/src/usage/service.test.ts b/packages/server/src/usage/service.test.ts
new file mode 100644
index 00000000..2acc1d24
--- /dev/null
+++ b/packages/server/src/usage/service.test.ts
@@ -0,0 +1,70 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import { getProviderUsage, resolveUsageProvider, selectModelWindows } from "./service"
+import type { ProviderResult } from "./types"
+
+const providerIds = [
+  "codex",
+  "github-copilot",
+  "google",
+  "kimi-for-coding",
+  "nano-gpt",
+  "openrouter",
+  "zai-coding-plan",
+  "zhipuai-coding-plan",
+  "minimax-coding-plan",
+  "minimax-cn-coding-plan",
+  "ollama-cloud",
+  "wafer",
+  "opencode-go",
+  "cursor",
+]
+
+test("registers every supported usage provider", () => {
+  for (const providerId of providerIds) {
+    assert.equal(resolveUsageProvider(providerId)?.id, providerId)
+  }
+})
+
+test("maps OpenCode provider aliases to their usage provider", () => {
+  assert.equal(resolveUsageProvider("openai")?.id, "codex")
+  assert.equal(resolveUsageProvider("copilot")?.id, "github-copilot")
+  assert.equal(resolveUsageProvider("gemini")?.id, "google")
+  assert.equal(resolveUsageProvider("opencode")?.id, "opencode-go")
+})
+
+test("does not use Claude subscription OAuth credentials", () => {
+  assert.equal(resolveUsageProvider("anthropic"), null)
+  assert.equal(resolveUsageProvider("claude"), null)
+})
+
+test("selects model-specific windows by normalized model id", () => {
+  const result: ProviderResult = {
+    providerId: "google",
+    providerName: "Google",
+    ok: true,
+    configured: true,
+    fetchedAt: 1,
+    usage: {
+      windows: {},
+      models: {
+        "gemini/gemini-2.5-flash": {
+          windows: {
+            daily: { usedPercent: 25, remainingPercent: 75, windowSeconds: 86_400, resetAt: null },
+          },
+        },
+      },
+    },
+  }
+
+  assert.equal(selectModelWindows(result, "models/gemini-2.5-flash").daily?.usedPercent, 25)
+})
+
+test("returns a stable unsupported response without making a provider request", async () => {
+  const response = await getProviderUsage("unknown-provider", { modelId: "model" })
+  assert.equal(response.supported, false)
+  assert.equal(response.configured, false)
+  assert.equal(response.providerId, null)
+  assert.deepEqual(response.windows, {})
+})
diff --git a/packages/server/src/usage/service.ts b/packages/server/src/usage/service.ts
new file mode 100644
index 00000000..3601f97e
--- /dev/null
+++ b/packages/server/src/usage/service.ts
@@ -0,0 +1,91 @@
+import type { ProviderUsageResponse, ProviderUsageWindow } from "../api-types"
+import { apiKeyProviders } from "./providers/api-key"
+import { googleProviders } from "./providers/google"
+import { miniMaxProviders } from "./providers/minimax"
+import { oauthProviders } from "./providers/oauth"
+import { specialProviders } from "./providers/special"
+import type { ProviderResult, UsageProvider } from "./types"
+
+const CACHE_TTL_MS = 60_000
+const providers = [...oauthProviders, ...apiKeyProviders, ...miniMaxProviders, ...googleProviders, ...specialProviders]
+const registry = new Map<string, UsageProvider>()
+
+for (const provider of providers) {
+  registry.set(provider.id, provider)
+  for (const alias of provider.aliases) registry.set(alias.toLowerCase(), provider)
+}
+
+const cache = new Map<string, { result: ProviderResult; expiresAt: number }>()
+const pending = new Map<string, Promise<ProviderResult>>()
+
+export function resolveUsageProvider(providerId: string): UsageProvider | null {
+  return registry.get(providerId.trim().toLowerCase()) ?? null
+}
+
+function normalizeModelId(value: string): string {
+  return value.toLowerCase().replace(/^models\//, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")
+}
+
+export function selectModelWindows(result: ProviderResult, modelId?: string): Record<string, ProviderUsageWindow> {
+  const usage = result.usage
+  if (!usage) return {}
+  if (!modelId || !usage.models) return usage.windows
+  const target = normalizeModelId(modelId)
+  const entries = Object.entries(usage.models)
+  const exact = entries.find(([name]) => normalizeModelId(name.split("/").pop() ?? name) === target)
+  if (exact) return exact[1].windows
+  const partial = entries.find(([name]) => {
+    const candidate = normalizeModelId(name.split("/").pop() ?? name)
+    return candidate.includes(target) || target.includes(candidate)
+  })
+  return partial?.[1].windows ?? usage.windows
+}
+
+async function fetchProvider(provider: UsageProvider): Promise<ProviderResult> {
+  const cached = cache.get(provider.id)
+  if (cached && cached.expiresAt > Date.now()) return cached.result
+  const inFlight = pending.get(provider.id)
+  if (inFlight) return inFlight
+  const request = provider.fetchQuota().then((result) => {
+    cache.set(provider.id, { result, expiresAt: Date.now() + CACHE_TTL_MS })
+    return result
+  }).finally(() => pending.delete(provider.id))
+  pending.set(provider.id, request)
+  return request
+}
+
+export async function getProviderUsage(
+  requestedProviderId: string,
+  options: { modelId?: string } = {},
+): Promise<ProviderUsageResponse> {
+  const provider = resolveUsageProvider(requestedProviderId)
+  if (!provider) {
+    return {
+      requestedProviderId,
+      providerId: null,
+      providerName: requestedProviderId,
+      modelId: options.modelId,
+      supported: false,
+      configured: false,
+      ok: false,
+      windows: {},
+      fetchedAt: Date.now(),
+    }
+  }
+  const result = await fetchProvider(provider)
+  return {
+    requestedProviderId,
+    providerId: provider.id,
+    providerName: result.providerName,
+    modelId: options.modelId,
+    supported: true,
+    configured: result.configured,
+    ok: result.ok,
+    windows: selectModelWindows(result, options.modelId),
+    fetchedAt: result.fetchedAt,
+  }
+}
+
+export function clearProviderUsageCache(): void {
+  cache.clear()
+}
diff --git a/packages/server/src/usage/shared.test.ts b/packages/server/src/usage/shared.test.ts
new file mode 100644
index 00000000..c9fc67d1
--- /dev/null
+++ b/packages/server/src/usage/shared.test.ts
@@ -0,0 +1,34 @@
+import assert from "node:assert/strict"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import test from "node:test"
+
+import { getCredential, readOpenCodeAuth, toTimestamp, toUsageWindow } from "./shared"
+
+test("reads the explicit OpenCode auth file without exposing credentials through the API", () => {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), "codenomad-usage-"))
+  const authFile = path.join(directory, "auth.json")
+  const previous = process.env.OPENCODE_AUTH_FILE
+  fs.writeFileSync(authFile, JSON.stringify({ openai: { type: "oauth", access: "secret-token" } }))
+  process.env.OPENCODE_AUTH_FILE = authFile
+
+  try {
+    assert.equal((readOpenCodeAuth().openai as Record<string, unknown>).access, "secret-token")
+    assert.equal(getCredential(["openai"], ["access"]), "secret-token")
+  } finally {
+    if (previous === undefined) delete process.env.OPENCODE_AUTH_FILE
+    else process.env.OPENCODE_AUTH_FILE = previous
+    fs.rmSync(directory, { recursive: true, force: true })
+  }
+})
+
+test("normalizes percentages and timestamps", () => {
+  assert.deepEqual(toUsageWindow({ usedPercent: 120, resetAt: null }), {
+    usedPercent: 100,
+    remainingPercent: 0,
+    windowSeconds: null,
+    resetAt: null,
+  })
+  assert.equal(toTimestamp(1_700_000_000), 1_700_000_000_000)
+})
diff --git a/packages/server/src/usage/shared.ts b/packages/server/src/usage/shared.ts
new file mode 100644
index 00000000..958ca31c
--- /dev/null
+++ b/packages/server/src/usage/shared.ts
@@ -0,0 +1,148 @@
+import fs from "fs"
+import os from "os"
+import path from "path"
+
+import type { ProviderUsageWindow } from "../api-types"
+import type { AuthEntry, AuthFile, ProviderResult, ProviderUsage } from "./types"
+
+const REQUEST_TIMEOUT_MS = 15_000
+
+function authFileCandidates(): string[] {
+  const home = os.homedir()
+  const candidates = [
+    process.env.OPENCODE_AUTH_FILE,
+    process.env.OPENCODE_DATA_DIR ? path.join(process.env.OPENCODE_DATA_DIR, "auth.json") : undefined,
+    process.env.XDG_DATA_HOME ? path.join(process.env.XDG_DATA_HOME, "opencode", "auth.json") : undefined,
+    path.join(home, ".local", "share", "opencode", "auth.json"),
+    process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, "opencode", "Data", "auth.json") : undefined,
+    process.env.APPDATA ? path.join(process.env.APPDATA, "opencode", "auth.json") : undefined,
+    path.join(home, "Library", "Application Support", "opencode", "auth.json"),
+  ]
+  return Array.from(new Set(candidates.filter((candidate): candidate is string => Boolean(candidate))))
+}
+
+export function readOpenCodeAuth(): AuthFile {
+  for (const candidate of authFileCandidates()) {
+    try {
+      const parsed: unknown = JSON.parse(fs.readFileSync(candidate, "utf8"))
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed as AuthFile
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") continue
+    }
+  }
+  return {}
+}
+
+export function getAuthEntry(aliases: readonly string[]): AuthEntry | null {
+  const auth = readOpenCodeAuth()
+  for (const alias of aliases) {
+    const value = auth[alias]
+    if (typeof value === "string" && value.trim()) return { token: value.trim() }
+    if (value && typeof value === "object" && !Array.isArray(value)) return value as AuthEntry
+  }
+  return null
+}
+
+export function getString(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null
+}
+
+export function getCredential(aliases: readonly string[], fields: readonly string[]): string | null {
+  const entry = getAuthEntry(aliases)
+  if (!entry) return null
+  for (const field of fields) {
+    const value = getString(entry[field])
+    if (value) return value
+  }
+  return null
+}
+
+export function asObject(value: unknown): Record<string, any> | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, any>) : null
+}
+
+export function toNumber(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+  return null
+}
+
+export function toTimestamp(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value < 1_000_000_000_000 ? value * 1000 : value
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Date.parse(value)
+    return Number.isNaN(parsed) ? null : parsed
+  }
+  return null
+}
+
+export function toUsageWindow(input: {
+  usedPercent: number | null
+  windowSeconds?: number | null
+  resetAt?: number | null
+  valueLabel?: string | null
+}): ProviderUsageWindow {
+  const usedPercent = input.usedPercent === null ? null : Math.max(0, Math.min(100, input.usedPercent))
+  return {
+    usedPercent,
+    remainingPercent: usedPercent === null ? null : 100 - usedPercent,
+    windowSeconds: input.windowSeconds ?? null,
+    resetAt: input.resetAt ?? null,
+    ...(input.valueLabel ? { valueLabel: input.valueLabel } : {}),
+  }
+}
+
+export function resolveWindowLabel(windowSeconds: number | null): string {
+  if (!windowSeconds) return "usage"
+  if (windowSeconds % 86_400 === 0) {
+    const days = windowSeconds / 86_400
+    return days === 7 ? "weekly" : `${days}d`
+  }
+  if (windowSeconds % 3600 === 0) return `${windowSeconds / 3600}h`
+  return `${windowSeconds}s`
+}
+
+export function result(
+  providerId: string,
+  providerName: string,
+  input: { ok: boolean; configured: boolean; usage?: ProviderUsage; error?: string },
+): ProviderResult {
+  return {
+    providerId,
+    providerName,
+    ok: input.ok,
+    configured: input.configured,
+    usage: input.usage ?? null,
+    fetchedAt: Date.now(),
+    ...(input.error ? { error: input.error } : {}),
+  }
+}
+
+export function notConfigured(providerId: string, providerName: string): ProviderResult {
+  return result(providerId, providerName, { ok: false, configured: false, error: "Not configured" })
+}
+
+export async function fetchJson(url: string, init: RequestInit = {}): Promise<any> {
+  const response = await fetch(url, { ...init, signal: init.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS) })
+  if (!response.ok) throw new Error(`Provider returned HTTP ${response.status}`)
+  return response.json()
+}
+
+export async function safeFetch(
+  providerId: string,
+  providerName: string,
+  operation: () => Promise<ProviderUsage>,
+): Promise<ProviderResult> {
+  try {
+    return result(providerId, providerName, { ok: true, configured: true, usage: await operation() })
+  } catch (error) {
+    return result(providerId, providerName, {
+      ok: false,
+      configured: true,
+      error: error instanceof Error ? error.message : "Request failed",
+    })
+  }
+}
diff --git a/packages/server/src/usage/types.ts b/packages/server/src/usage/types.ts
new file mode 100644
index 00000000..60a59f5a
--- /dev/null
+++ b/packages/server/src/usage/types.ts
@@ -0,0 +1,26 @@
+import type { ProviderUsageWindow } from "../api-types"
+
+export interface ProviderUsage {
+  windows: Record<string, ProviderUsageWindow>
+  models?: Record<string, { windows: Record<string, ProviderUsageWindow> }>
+}
+
+export interface ProviderResult {
+  providerId: string
+  providerName: string
+  ok: boolean
+  configured: boolean
+  usage: ProviderUsage | null
+  fetchedAt: number
+  error?: string
+}
+
+export interface UsageProvider {
+  id: string
+  name: string
+  aliases: readonly string[]
+  fetchQuota: () => Promise<ProviderResult>
+}
+
+export type AuthEntry = Record<string, unknown>
+export type AuthFile = Record<string, unknown>
diff --git a/packages/server/src/workspaces/__tests__/spawn.test.ts b/packages/server/src/workspaces/__tests__/spawn.test.ts
index a5fb2eda..d11d8a66 100644
--- a/packages/server/src/workspaces/__tests__/spawn.test.ts
+++ b/packages/server/src/workspaces/__tests__/spawn.test.ts
@@ -1,7 +1,10 @@
 import assert from "node:assert/strict"
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
 import { describe, it } from "node:test"
 
-import { buildWindowsSpawnSpec, buildWslSignalSpec, parseWslUncPath, resolveWslWorkingDirectory } from "../spawn"
+import { buildWindowsSpawnSpec, parseWslUncPath, resolveWslWorkingDirectory } from "../spawn"
 
 describe("parseWslUncPath", () => {
   it("parses WSL UNC paths into distro and linux path", () => {
@@ -47,6 +50,70 @@ describe("resolveWslWorkingDirectory", () => {
 })
 
 describe("buildWindowsSpawnSpec", () => {
+  it("classifies native executables separately from script and shell wrappers", () => {
+    assert.equal(buildWindowsSpawnSpec("opencode.exe", []).processKind, "windows-direct")
+    assert.equal(buildWindowsSpawnSpec("opencode.cmd", []).processKind, "windows-wrapper")
+    assert.equal(buildWindowsSpawnSpec("powershell.exe", []).processKind, "windows-wrapper")
+  })
+
+  it("conservatively classifies bare commands as wrappers", () => {
+    assert.equal(buildWindowsSpawnSpec("opencode", []).processKind, "windows-wrapper")
+  })
+
+  it("resolves a bare cmd shim from a quoted PATH entry and wraps its absolute path", { skip: process.platform !== "win32" }, () => {
+    const root = mkdtempSync(path.join(tmpdir(), "codenomad-spawn-"))
+    const cwd = path.join(root, "workspace")
+    const bin = path.join(root, "bin with spaces")
+    mkdirSync(cwd)
+    mkdirSync(bin)
+    const shim = path.join(bin, "opencode.cmd")
+    writeFileSync(shim, "@echo off\r\n")
+
+    try {
+      const spec = buildWindowsSpawnSpec("opencode", ["serve"], {
+        cwd,
+        env: { Path: `"${bin}"`, PathExt: ".CMD;.EXE", ComSpec: "test-cmd.exe" },
+      })
+
+      assert.equal(spec.command, "test-cmd.exe")
+      assert.equal(spec.processKind, "windows-wrapper")
+      assert.equal(spec.options.windowsVerbatimArguments, true)
+      assert.match(spec.args[3] ?? "", new RegExp(escapeRegex(path.win32.resolve(shim)), "i"))
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it("honors PATHEXT precedence when both native and shim files exist", { skip: process.platform !== "win32" }, () => {
+    const root = mkdtempSync(path.join(tmpdir(), "codenomad-spawn-"))
+    writeFileSync(path.join(root, "opencode.cmd"), "@echo off\r\n")
+    writeFileSync(path.join(root, "opencode.exe"), "")
+
+    try {
+      const spec = buildWindowsSpawnSpec("opencode", [], {
+        cwd: root,
+        env: { PATH: "", PATHEXT: ".EXE;.CMD" },
+      })
+
+      assert.equal(spec.command.toLowerCase(), path.win32.resolve(root, "opencode.exe").toLowerCase())
+      assert.equal(spec.processKind, "windows-direct")
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it("leaves an unresolved bare command unchanged without injecting a shell", () => {
+    const spec = buildWindowsSpawnSpec("missing-opencode", ["serve"], {
+      cwd: String.raw`C:\missing-workspace`,
+      env: { PATH: "", PATHEXT: ".CMD;.EXE", ComSpec: "must-not-run.exe" },
+    })
+
+    assert.equal(spec.command, "missing-opencode")
+    assert.deepEqual(spec.args, ["serve"])
+    assert.equal(spec.processKind, "windows-wrapper")
+    assert.equal(spec.options.windowsVerbatimArguments, undefined)
+  })
+
   it("wraps WSL binaries with wsl.exe and propagates required env vars", () => {
     const spec = buildWindowsSpawnSpec(
       String.raw`\\wsl.localhost\Ubuntu\home\dev\.opencode\bin\opencode`,
@@ -200,7 +267,7 @@ describe("buildWindowsSpawnSpec", () => {
       "--exec",
       "sh",
       "-lc",
-      `printf '%s%s\\n' '__CODENOMAD_WSL_PID__:' "$$" && cd "$1" && shift && exec "$@"`,
+      `codenomad_pgid=$(ps -o pgid= -p "$$" 2>/dev/null | tr -d '[:space:]'); codenomad_start=$(awk '{print $22}' "/proc/$$/stat" 2>/dev/null); codenomad_boot=$(cat /proc/sys/kernel/random/boot_id 2>/dev/null); test -n "$codenomad_pgid" && test -n "$codenomad_start" && test -n "$codenomad_boot" && printf '%s%s:%s:%s:%s\\n' '__CODENOMAD_WSL_PID__:' "$$" "$codenomad_pgid" "$codenomad_start" "$codenomad_boot" && cd "$1" && shift && exec "$@"`,
       "codenomad-wsl-launch",
       "/home/dev/workspace",
       "/home/dev/.opencode/bin/opencode",
@@ -209,10 +276,8 @@ describe("buildWindowsSpawnSpec", () => {
     assert.equal(spec.wsl?.pidMarker, "__CODENOMAD_WSL_PID__:")
   })
 
-  it("builds the WSL kill command for tracked Linux PIDs", () => {
-    const spec = buildWslSignalSpec("Ubuntu", 4321, "SIGTERM")
-
-    assert.equal(spec.command, "wsl.exe")
-    assert.deepEqual(spec.args, ["--distribution", "Ubuntu", "--exec", "kill", "-TERM", "4321"])
-  })
 })
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
diff --git a/packages/server/src/workspaces/__tests__/workspace-identity.test.ts b/packages/server/src/workspaces/__tests__/workspace-identity.test.ts
new file mode 100644
index 00000000..ccf8e6ca
--- /dev/null
+++ b/packages/server/src/workspaces/__tests__/workspace-identity.test.ts
@@ -0,0 +1,186 @@
+import assert from "node:assert/strict"
+import { mkdtemp, mkdir, rm, symlink } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, describe, it } from "node:test"
+import pino from "pino"
+
+import { EventBus } from "../../events/bus"
+import { WorkspaceManager } from "../manager"
+import { normalizeWorkspaceIdentityPath, resolveWorkspaceIdentity } from "../workspace-identity"
+
+const temporaryDirectories: string[] = []
+const runtimeResult = (pid = 123) => ({
+  pid,
+  port: 4321,
+  exitPromise: new Promise<never>(() => undefined),
+  getLastOutput: () => "",
+})
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((resolvePromise) => { resolve = resolvePromise })
+  return { promise, resolve }
+}
+
+afterEach(async () => {
+  await Promise.all(temporaryDirectories.splice(0).map((directory) => rm(directory, { force: true, recursive: true })))
+})
+
+async function createLinkedWorkspace() {
+  const root = await mkdtemp(path.join(os.tmpdir(), "codenomad-workspace-identity-"))
+  temporaryDirectories.push(root)
+  const target = path.join(root, "target")
+  const link = path.join(root, "link")
+  await mkdir(target)
+  await symlink(target, link, process.platform === "win32" ? "junction" : "dir")
+  return { root, target, link }
+}
+
+function createManager(rootDir: string) {
+  const logger = pino({ level: "silent" })
+  const manager = new WorkspaceManager({
+    rootDir,
+    settings: { getOwner: () => ({ environmentVariables: {} }) },
+    binaryResolver: { resolve: () => ({ path: process.execPath, label: "Node.js", version: process.version }) },
+    eventBus: new EventBus(logger),
+    logger,
+    getServerBaseUrl: () => "http://127.0.0.1:3000",
+  } as unknown as ConstructorParameters<typeof WorkspaceManager>[0])
+  ;(manager as any).runtime.launch = async () => runtimeResult()
+  ;(manager as any).runtime.stop = async () => undefined
+  ;(manager as any).waitForWorkspaceReadiness = async () => undefined
+  return manager
+}
+
+async function waitForOwners(manager: WorkspaceManager, count: number) {
+  while ([...(manager as any).pendingWorkspaceCreations.values()][0]?.ownership.size !== count) {
+    await new Promise((resolve) => setImmediate(resolve))
+  }
+}
+
+async function createSharedLaunch() {
+  const { root, target, link } = await createLinkedWorkspace()
+  const manager = createManager(root)
+  const launchGate = deferred<void>()
+  let launches = 0
+  ;(manager as any).runtime.launch = async () => {
+    launches += 1
+    await launchGate.promise
+    return runtimeResult()
+  }
+  const leader = manager.create(target, undefined, { requestId: "leader" })
+  const follower = manager.create(link, undefined, { requestId: "follower" })
+  await waitForOwners(manager, 2)
+  return { manager, launchGate, leader, follower, launches: () => launches }
+}
+
+describe("workspace identity", () => {
+  it("normalizes Windows paths without affecting POSIX case", () => {
+    assert.equal(normalizeWorkspaceIdentityPath("C:\\Projects\\CodeNomad\\", "win32"), "c:\\projects\\codenomad\\")
+    assert.equal(normalizeWorkspaceIdentityPath(String.raw`\\Server\Share\Repo`, "win32"), String.raw`\\server\share\repo`)
+    assert.equal(normalizeWorkspaceIdentityPath("/Projects/CodeNomad/", "linux"), "/Projects/CodeNomad/")
+  })
+
+  it("canonicalizes aliases and falls back to an absolute identity for missing paths", async () => {
+    const { root, target, link } = await createLinkedWorkspace()
+    const [targetResult, linkResult, missing] = await Promise.all([
+      resolveWorkspaceIdentity(target, root),
+      resolveWorkspaceIdentity(link, root),
+      resolveWorkspaceIdentity("missing", root),
+    ])
+    const expectedMissing = path.resolve(root, "missing")
+
+    assert.equal(linkResult.identityKey, targetResult.identityKey)
+    assert.equal(linkResult.workspacePath, targetResult.workspacePath)
+    assert.equal(missing.workspacePath, expectedMissing)
+    assert.equal(missing.identityKey, normalizeWorkspaceIdentityPath(expectedMissing))
+  })
+
+  it("deduplicates active canonical aliases", async () => {
+    const { root, target, link } = await createLinkedWorkspace()
+    const manager = createManager(root)
+    const [first, second] = await Promise.all([manager.create(target), manager.create(link)])
+
+    assert.equal(Number(first.created) + Number(second.created), 1)
+    assert.equal(first.workspace.id, second.workspace.id)
+    assert.equal(manager.list().length, 1)
+  })
+
+  it("shares one in-flight launch between canonical aliases", async () => {
+    const shared = await createSharedLaunch()
+    shared.launchGate.resolve()
+    const [leader, follower] = await Promise.all([shared.leader, shared.follower])
+
+    assert.equal(shared.launches(), 1)
+    assert.equal(leader.workspace.id, follower.workspace.id)
+    assert.equal(Number(leader.created) + Number(follower.created), 1)
+    assert.equal(leader.workspace.status, "ready")
+  })
+
+  for (const cancelledRole of ["leader", "follower"] as const) {
+    it(`detaches a cancelled ${cancelledRole} without stopping its shared owner`, async () => {
+      const shared = await createSharedLaunch()
+      await shared.manager.cancelCreationRequest(cancelledRole)
+      shared.launchGate.resolve()
+      const cancelled = shared[cancelledRole]
+      const survivor = shared[cancelledRole === "leader" ? "follower" : "leader"]
+
+      await assert.rejects(cancelled, new RegExp(`creation request ${cancelledRole} was cancelled`))
+      const result = await survivor
+      assert.equal(shared.launches(), 1)
+      assert.equal(result.workspace.requestId, cancelledRole === "leader" ? "follower" : "leader")
+      assert.equal(shared.manager.list().length, 1)
+    })
+  }
+
+  for (const releasedRole of ["leader", "follower"] as const) {
+    it(`retains shared ownership when the ${releasedRole} releases and the other owner cancels`, async () => {
+      const shared = await createSharedLaunch()
+      shared.launchGate.resolve()
+      const [leader, follower] = await Promise.all([shared.leader, shared.follower])
+      assert.equal(leader.workspace.id, follower.workspace.id)
+
+      assert.equal(shared.manager.releaseCreationRequest(leader.workspace.id, releasedRole), true)
+      await shared.manager.cancelCreationRequest(releasedRole === "leader" ? "follower" : "leader")
+      assert.equal(shared.manager.list().length, 1)
+      assert.equal(shared.manager.get(leader.workspace.id)?.requestId, undefined)
+    })
+  }
+
+  it("releases a failed canonical reservation for retry", async () => {
+    const { root, target, link } = await createLinkedWorkspace()
+    const manager = createManager(root)
+    const launchGate = deferred<void>()
+    let launches = 0
+    ;(manager as any).runtime.launch = async () => {
+      launches += 1
+      await launchGate.promise
+      throw new Error("launch failed")
+    }
+    const failures = [
+      manager.create(target, undefined, { requestId: "first" }),
+      manager.create(link, undefined, { requestId: "second" }),
+    ]
+    await waitForOwners(manager, 2)
+    launchGate.resolve()
+    assert.deepEqual((await Promise.allSettled(failures)).map((result) => result.status), ["rejected", "rejected"])
+    assert.equal(launches, 1)
+
+    ;(manager as any).runtime.launch = async () => runtimeResult(456)
+    assert.equal((await manager.create(target)).created, true)
+  })
+
+  it("allows forced canonical duplicates without replacing the reusable workspace", async () => {
+    const { root, target, link } = await createLinkedWorkspace()
+    const manager = createManager(root)
+    const normal = await manager.create(target)
+    const forced = await manager.create(link, undefined, { forceNew: true })
+    assert.notEqual(normal.workspace.id, forced.workspace.id)
+
+    await manager.delete(forced.workspace.id)
+    const reused = await manager.create(link)
+    assert.equal(reused.created, false)
+    assert.equal(reused.workspace.id, normal.workspace.id)
+  })
+})
diff --git a/packages/server/src/workspaces/binary-path.test.ts b/packages/server/src/workspaces/binary-path.test.ts
new file mode 100644
index 00000000..9f748034
--- /dev/null
+++ b/packages/server/src/workspaces/binary-path.test.ts
@@ -0,0 +1,26 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import { binaryPathsEqual } from "./manager"
+
+test("matches regular Windows binary paths without case sensitivity", () => {
+  assert.equal(binaryPathsEqual(String.raw`C:\Tools\OpenCode.cmd`, String.raw`c:\tools\opencode.CMD`, "win32"), true)
+})
+
+test("matches WSL distro names without changing Linux path casing", () => {
+  assert.equal(
+    binaryPathsEqual(
+      String.raw`\\wsl.localhost\Ubuntu\home\dev\OpenCode`,
+      String.raw`\\wsl$\ubuntu\home\dev\OpenCode`,
+      "win32",
+    ),
+    true,
+  )
+  assert.equal(
+    binaryPathsEqual(
+      String.raw`\\wsl.localhost\Ubuntu\home\dev\OpenCode`,
+      String.raw`\\wsl$\ubuntu\home\dev\opencode`,
+      "win32",
+    ),
+    false,
+  )
+})
diff --git a/packages/server/src/workspaces/instance-client.ts b/packages/server/src/workspaces/instance-client.ts
new file mode 100644
index 00000000..59607c92
--- /dev/null
+++ b/packages/server/src/workspaces/instance-client.ts
@@ -0,0 +1,55 @@
+import { createOpencodeClient, type OpencodeClient } from "@opencode-ai/sdk/v2/client"
+import type { WorkspaceManager } from "./manager"
+
+const INSTANCE_HOST = "127.0.0.1"
+const LOOPBACK_TIMEOUT_MS = 10_000
+
+interface InstanceClientOptions {
+  timeoutMs?: number
+}
+
+/**
+ * Creates an OpenCode SDK client for direct loopback communication with a
+ * running workspace instance.
+ *
+ * Routes and body shapes come from the auto-generated SDK contract
+ * (`@opencode-ai/sdk`), eliminating handwritten URL construction that can
+ * drift between SDK versions. Other server modules that need to call the
+ * OpenCode instance directly should use this factory rather than building
+ * `http://127.0.0.1:{port}/...` URLs by hand.
+ *
+ * All requests carry a 10-second timeout — loopback calls should be
+ * near-instant; a hang indicates a stuck instance.
+ *
+ * The client is cheap to create (object only, no connection); create one per
+ * call or cache per instance as needed. Returns `null` when the instance has
+ * no open port yet.
+ */
+export function createInstanceClient(
+  workspaceManager: WorkspaceManager,
+  instanceId: string,
+  options: InstanceClientOptions = {},
+): OpencodeClient | null {
+  const port = workspaceManager.getInstancePort(instanceId)
+  if (!port) return null
+
+  const headers: Record<string, string> = {}
+  const authorization = workspaceManager.getInstanceAuthorizationHeader(instanceId)
+  if (authorization) {
+    headers.authorization = authorization
+  }
+
+  const workspace = workspaceManager.get(instanceId)
+  const timeoutMs = options.timeoutMs ?? LOOPBACK_TIMEOUT_MS
+
+  return createOpencodeClient({
+    baseUrl: `http://${INSTANCE_HOST}:${port}/`,
+    headers,
+    fetch: (url, init) =>
+      fetch(url, {
+        ...(init as RequestInit),
+        signal: (init as RequestInit)?.signal ?? AbortSignal.timeout(timeoutMs),
+      }),
+    ...(workspace?.path ? { directory: workspace.path } : {}),
+  })
+}
diff --git a/packages/server/src/workspaces/launch-cleanup.test.ts b/packages/server/src/workspaces/launch-cleanup.test.ts
new file mode 100644
index 00000000..2a2f34f8
--- /dev/null
+++ b/packages/server/src/workspaces/launch-cleanup.test.ts
@@ -0,0 +1,34 @@
+import assert from "node:assert/strict"
+import { spawnSync, type SpawnSyncReturns } from "node:child_process"
+import { describe, it } from "node:test"
+import { LAUNCH_CLEANUP_TOKEN_ENV, probeLaunchCleanupToken, signalLaunchCleanupToken } from "./process-identity"
+
+type Spawn = typeof import("node:child_process").spawnSync
+const result = (stdout: string): SpawnSyncReturns<string> => ({ pid: 1, output: [null, stdout, ""], stdout, stderr: "", status: 0, signal: null })
+
+describe("launch cleanup token adapter", () => {
+  it("passes the exact token to the bounded Linux environ probe", () => {
+    const token = "a".repeat(64), calls: any[] = []
+    const run = ((command: string, args: string[], options: object) => { calls.push(command, args, options); return result("CODENOMAD_PROCESS|5000|1|4242|150|boot-a|150\n") }) as unknown as Spawn
+    const probe = probeLaunchCleanupToken(run, token, 25)
+    assert.equal(probe.ok && probe.processes.get(5000)?.startOrder, "150")
+    assert.equal(calls[0], "sh")
+    assert.deepEqual([calls[2].timeout, calls[1].includes(LAUNCH_CLEANUP_TOKEN_ENV), calls[1].includes(token)], [25, true, true])
+    assert.match(calls[1][1], /\/proc\/\$1\/environ/)
+    assert.doesNotMatch(calls[1][1], /\bseq\b/)
+  })
+
+  it("executes a successful empty Linux token probe", { skip: process.platform !== "linux" }, () => {
+    const probe = probeLaunchCleanupToken(spawnSync, "f".repeat(64), 1_000)
+    assert.deepEqual(probe, { ok: true, processes: new Map() })
+  })
+
+  it("signals every exact-token target and rejects malformed records", () => {
+    const rows = "CODENOMAD_TARGET|4242|1|4242|100|boot-a|100\nCODENOMAD_TARGET|5000|1|4242|150|boot-a|150\nCODENOMAD_RESULT|1\n"
+    const run = ((() => result(rows)) as unknown) as Spawn
+    const cleanup = signalLaunchCleanupToken(run, "b".repeat(64), "SIGKILL", 25)
+    assert.deepEqual([cleanup.ok, cleanup.targets.map(({ pid }) => pid)], [true, [4242, 5000]])
+    const malformed = ((() => result("5000|1|4242|150|boot-a|150|truncated\n")) as unknown) as Spawn
+    assert.equal(probeLaunchCleanupToken(malformed, "c".repeat(64), 25).ok, false)
+  })
+})
diff --git a/packages/server/src/workspaces/manager.test.ts b/packages/server/src/workspaces/manager.test.ts
new file mode 100644
index 00000000..7b9a66e4
--- /dev/null
+++ b/packages/server/src/workspaces/manager.test.ts
@@ -0,0 +1,341 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import pino from "pino"
+
+import { EventBus } from "../events/bus"
+import {
+  WorkspaceWindowsTreeCleanupIncompleteError,
+  type ProcessExitInfo,
+  type WorkspaceRuntime,
+} from "./runtime"
+import {
+  WorkspaceCleanupTimeoutError,
+  WorkspaceLaunchCancelledError,
+  WorkspaceLaunchTimeoutError,
+  WorkspaceManager,
+  WorkspaceShutdownError,
+} from "./manager"
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise
+    reject = rejectPromise
+  })
+  return { promise, resolve, reject }
+}
+
+class ControlledRuntime {
+  readonly launchResult = deferred<Awaited<ReturnType<WorkspaceRuntime["launch"]>>>()
+  readonly launchCalled = deferred<string>()
+  readonly active = new Set<string>()
+  stopCalls = 0
+  failStops = 0
+  onExit?: (info: ProcessExitInfo) => void
+
+  launch: WorkspaceRuntime["launch"] = (options) => {
+    this.active.add(options.workspaceId)
+    this.onExit = options.onExit
+    this.launchCalled.resolve(options.workspaceId)
+    options.signal?.addEventListener("abort", () => this.launchResult.reject(options.signal?.reason), { once: true })
+    return this.launchResult.promise
+  }
+
+  stop: WorkspaceRuntime["stop"] = async (workspaceId) => {
+    this.stopCalls += 1
+    if (this.failStops-- > 0) throw new Error("controlled stop failure")
+    this.active.delete(workspaceId)
+  }
+
+  resolveLaunch(): void {
+    this.launchResult.resolve({
+      pid: 1234,
+      port: 4321,
+      exitPromise: new Promise<ProcessExitInfo>(() => undefined),
+      getLastOutput: () => "",
+    })
+  }
+}
+
+function createHarness(options: {
+  shutdownTimeoutMs?: number
+  launchTimeoutMs?: number
+  setTimeout?: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>
+  clearTimeout?: (timer: ReturnType<typeof setTimeout>) => void
+} = {}) {
+  const eventBus = new EventBus()
+  const runtime = new ControlledRuntime()
+  const readiness = deferred<string | undefined>()
+  const started: string[] = []
+  const stopped: string[] = []
+  eventBus.on("workspace.started", (event) => started.push(event.workspace.id))
+  eventBus.on("workspace.stopped", (event) => stopped.push(event.workspaceId))
+  const manager = new WorkspaceManager({
+    rootDir: process.cwd(),
+    settings: { getOwner: () => ({}) } as never,
+    binaryResolver: { resolve: () => ({ path: "test-opencode", label: "test-opencode" }) } as never,
+    eventBus,
+    logger: pino({ level: "silent" }),
+    getServerBaseUrl: () => "http://127.0.0.1:4000",
+    runtime,
+    ...options,
+  })
+  ;(manager as any).waitForWorkspaceReadiness = ({ signal }: { signal?: AbortSignal }) => Promise.race([
+    readiness.promise,
+    new Promise<never>((_resolve, reject) => {
+      const cancel = () => reject(signal?.reason)
+      signal?.addEventListener("abort", cancel, { once: true })
+      if (signal?.aborted) cancel()
+    }),
+  ])
+  return { manager, runtime, readiness, started, stopped }
+}
+
+async function createReady(harness: ReturnType<typeof createHarness>) {
+  const creation = harness.manager.create(process.cwd())
+  const workspaceId = await harness.runtime.launchCalled.promise
+  harness.runtime.resolveLaunch()
+  harness.readiness.resolve(undefined)
+  await creation
+  return workspaceId
+}
+
+describe("workspace manager lifecycle", () => {
+  for (const boundary of ["launch", "readiness", "shutdown"] as const) {
+    it(`cancels and cleans a workspace during ${boundary}`, async () => {
+      const harness = createHarness()
+      const creation = harness.manager.create(process.cwd())
+      const workspaceId = await harness.runtime.launchCalled.promise
+      let cleanup: Promise<unknown>
+      if (boundary === "readiness") {
+        harness.runtime.resolveLaunch()
+        await new Promise<void>((resolve) => setImmediate(resolve))
+        cleanup = harness.manager.delete(workspaceId)
+      } else {
+        cleanup = boundary === "shutdown" ? harness.manager.shutdown() : harness.manager.delete(workspaceId)
+        harness.runtime.resolveLaunch()
+      }
+
+      await assert.rejects(creation, WorkspaceLaunchCancelledError)
+      await cleanup
+      assert.deepEqual([harness.runtime.active.size, harness.started, harness.manager.list(), harness.stopped],
+        [0, [], [], boundary === "readiness" ? [workspaceId] : []])
+    })
+  }
+
+  it("shares failed cleanup and allows a later delete retry", async () => {
+    const harness = createHarness()
+    const workspaceId = await createReady(harness)
+    harness.runtime.failStops = 2
+
+    const first = harness.manager.delete(workspaceId)
+    const concurrent = harness.manager.delete(workspaceId)
+    assert.strictEqual(first, concurrent)
+    const failures = await Promise.allSettled([first, concurrent])
+    assert.deepEqual(failures.map((result) => result.status), ["rejected", "rejected"])
+    assert.equal(harness.runtime.active.has(workspaceId), true)
+
+    await harness.manager.delete(workspaceId)
+    assert.equal(harness.runtime.active.has(workspaceId), false)
+    assert.equal(harness.manager.get(workspaceId), undefined)
+  })
+
+  it("retries cancellation deletion for an already-cancelled request", async () => {
+    const harness = createHarness()
+    const creation = harness.manager.create(process.cwd(), undefined, { requestId: "retry-cancel" })
+    const workspaceId = await harness.runtime.launchCalled.promise
+    harness.runtime.resolveLaunch()
+    harness.readiness.resolve(undefined)
+    await creation
+    harness.runtime.failStops = 2
+
+    await assert.rejects(harness.manager.cancelCreationRequest("retry-cancel"), /controlled stop failure/)
+    assert.equal(harness.manager.get(workspaceId)?.id, workspaceId)
+    assert.equal(harness.runtime.active.has(workspaceId), true)
+
+    await harness.manager.cancelCreationRequest("retry-cancel")
+    assert.equal(harness.manager.get(workspaceId), undefined)
+    assert.equal(harness.runtime.active.has(workspaceId), false)
+    assert.deepEqual(harness.stopped, [workspaceId])
+  })
+
+  it("gives release and cancellation one terminal winner", async () => {
+    const cancelled = createHarness()
+    const cancelledCreation = cancelled.manager.create(process.cwd(), undefined, { requestId: "cancel-wins" })
+    const cancelledId = await cancelled.runtime.launchCalled.promise
+    cancelled.runtime.resolveLaunch()
+    cancelled.readiness.resolve(undefined)
+    await cancelledCreation
+    const stopStarted = deferred<void>()
+    const finishStop = deferred<void>()
+    const originalStop = cancelled.runtime.stop
+    cancelled.runtime.stop = async (workspaceId) => {
+      stopStarted.resolve()
+      await finishStop.promise
+      await originalStop(workspaceId)
+    }
+
+    const cancellation = cancelled.manager.cancelCreationRequest("cancel-wins")
+    await stopStarted.promise
+    assert.equal(cancelled.manager.releaseCreationRequest(cancelledId, "cancel-wins"), false)
+    assert.equal(cancelled.manager.get(cancelledId)?.id, cancelledId)
+    finishStop.resolve()
+    await cancellation
+    assert.equal(cancelled.manager.get(cancelledId), undefined)
+
+    const released = createHarness()
+    const releasedCreation = released.manager.create(process.cwd(), undefined, { requestId: "release-wins" })
+    const releasedId = await released.runtime.launchCalled.promise
+    released.runtime.resolveLaunch()
+    released.readiness.resolve(undefined)
+    await releasedCreation
+
+    assert.equal(released.manager.releaseCreationRequest(releasedId, "release-wins"), true)
+    await released.manager.cancelCreationRequest("release-wins")
+    assert.equal(released.manager.releaseCreationRequest(releasedId, "release-wins"), true)
+    assert.equal(released.manager.get(releasedId)?.id, releasedId)
+    assert.equal(released.runtime.active.has(releasedId), true)
+  })
+
+  it("retains unresolved pre-creation cancellation until its delayed create", async () => {
+    const harness = createHarness()
+    const requestIds = Array.from({ length: 1_025 }, (_, index) => `pending-cancel-${index}`)
+    await Promise.all(requestIds.map((requestId) => harness.manager.cancelCreationRequest(requestId)))
+
+    assert.equal((harness.manager as any).cancelledCreationRequests.size, requestIds.length)
+    await assert.rejects(
+      harness.manager.create(process.cwd(), undefined, { requestId: requestIds[0] }),
+      /was cancelled/,
+    )
+    assert.equal((harness.manager as any).cancelledCreationRequests.has(requestIds[0]), false)
+    assert.equal((harness.manager as any).cancelledCreationRequests.size, requestIds.length - 1)
+  })
+
+  it("returns scoped correlation while an ordinary shared launch remains retained", async () => {
+    const harness = createHarness()
+    const ordinary = harness.manager.create(process.cwd())
+    const workspaceId = await harness.runtime.launchCalled.promise
+    const scoped = harness.manager.create(process.cwd(), undefined, { requestId: "restore-shared" })
+    harness.runtime.resolveLaunch()
+    harness.readiness.resolve(undefined)
+
+    const [ordinaryResult, scopedResult] = await Promise.all([ordinary, scoped])
+    assert.equal(ordinaryResult.created, true)
+    assert.equal(ordinaryResult.workspace.requestId, undefined)
+    assert.equal(scopedResult.created, false)
+    assert.equal(scopedResult.workspace.id, workspaceId)
+    assert.equal(scopedResult.workspace.requestId, "restore-shared")
+
+    assert.equal(harness.manager.releaseCreationRequest(workspaceId, "restore-shared"), true)
+    assert.equal(harness.manager.get(workspaceId)?.id, workspaceId)
+    assert.equal(harness.runtime.active.has(workspaceId), true)
+
+    const reused = await harness.manager.create(process.cwd(), undefined, { requestId: "restore-reused" })
+    assert.equal(reused.workspace.requestId, "restore-reused")
+    await harness.manager.cancelCreationRequest("restore-reused")
+    assert.equal(harness.manager.get(workspaceId)?.id, workspaceId)
+    assert.equal(harness.runtime.active.has(workspaceId), true)
+    await assert.rejects(
+      harness.manager.create(process.cwd(), undefined, { requestId: "restore-reused" }),
+      /was cancelled/,
+    )
+    assert.equal(harness.manager.releaseCreationRequest(workspaceId, "restore-reused"), false)
+  })
+
+  for (const boundary of ["runtime launch", "health readiness"] as const) {
+    it(`applies one shared end-to-end deadline during ${boundary} and cleans up`, async () => {
+      const deadlines: Array<() => void> = []
+      const harness = createHarness({
+        launchTimeoutMs: 25,
+        setTimeout: ((callback: () => void) => {
+          const timer = { active: true }
+          deadlines.push(() => { if (timer.active) callback() })
+          return timer as unknown as ReturnType<typeof setTimeout>
+        }) as typeof setTimeout,
+        clearTimeout: ((timer: { active: boolean }) => { timer.active = false }) as unknown as typeof clearTimeout,
+      })
+      const first = harness.manager.create(process.cwd(), undefined, { requestId: "deadline-one" })
+      const workspaceId = await harness.runtime.launchCalled.promise
+      const shared = harness.manager.create(process.cwd(), undefined, { requestId: "deadline-two" })
+      while ([...(harness.manager as any).pendingWorkspaceCreations.values()][0]?.ownership.size !== 2) {
+        await new Promise<void>((resolve) => setImmediate(resolve))
+      }
+      if (boundary === "health readiness") {
+        harness.runtime.resolveLaunch()
+        await new Promise<void>((resolve) => setImmediate(resolve))
+      }
+
+      for (const fire of deadlines) fire()
+      const outcomes = await Promise.allSettled([first, shared])
+      assert.deepEqual(outcomes.map((outcome) => outcome.status), ["rejected", "rejected"])
+      assert.ok(outcomes.every((outcome) => outcome.status === "rejected" && outcome.reason instanceof WorkspaceLaunchTimeoutError))
+      assert.strictEqual((outcomes[0] as PromiseRejectedResult).reason, (outcomes[1] as PromiseRejectedResult).reason)
+      assert.equal(harness.runtime.active.has(workspaceId), false)
+      assert.equal(harness.runtime.stopCalls >= 1, true)
+      assert.deepEqual(harness.manager.list(), [])
+    })
+  }
+
+  it("bounds shutdown instead of waiting forever", async () => {
+    let fireDeadline!: () => void
+    let cleared = 0
+    const harness = createHarness({
+      shutdownTimeoutMs: 25,
+      setTimeout: ((callback: () => void) => {
+        fireDeadline = callback
+        return {} as ReturnType<typeof setTimeout>
+      }) as typeof setTimeout,
+      clearTimeout: () => { cleared += 1 },
+    } as never)
+    const workspaceId = await createReady(harness)
+    cleared = 0
+    harness.runtime.stop = () => new Promise<void>(() => undefined)
+
+    const shutdown = harness.manager.shutdown()
+    fireDeadline()
+    await assert.rejects(shutdown, WorkspaceCleanupTimeoutError)
+    assert.equal(harness.manager.get(workspaceId)?.status, "ready")
+    assert.equal(cleared, 1)
+  })
+
+  it("publishes stopped exactly once for normal exit, readiness failure, and manager cleanup", async () => {
+    const normal = createHarness()
+    const normalId = await createReady(normal)
+    normal.runtime.onExit?.({ workspaceId: normalId, code: 0, signal: null, requested: false })
+    await normal.manager.delete(normalId)
+    assert.deepEqual(normal.stopped, [normalId])
+
+    const failed = createHarness()
+    const failedCreation = failed.manager.create(process.cwd())
+    const failedId = await failed.runtime.launchCalled.promise
+    failed.runtime.resolveLaunch()
+    failed.readiness.reject(new Error("not ready"))
+    await assert.rejects(failedCreation, /not ready/)
+    assert.deepEqual(failed.stopped, [failedId])
+
+    const cleaned = createHarness()
+    const cleanedId = await createReady(cleaned)
+    await cleaned.manager.shutdown()
+    assert.deepEqual(cleaned.stopped, [cleanedId])
+  })
+
+  for (const [name, failure] of [
+    ["cleanup failures", new Error("stop failed")],
+    ["incomplete Windows tree cleanup", new WorkspaceWindowsTreeCleanupIncompleteError("workspace", 4242, ["taskkill failed"])],
+  ] as const) {
+    it(`aggregates ${name} during shutdown`, async () => {
+      const harness = createHarness()
+      const workspaceId = await createReady(harness)
+      harness.runtime.stop = async () => { throw failure }
+
+      await assert.rejects(harness.manager.shutdown(), (error: unknown) => {
+        assert.ok(error instanceof WorkspaceShutdownError)
+        assert.strictEqual(error.errors[0], failure)
+        return true
+      })
+      assert.equal(harness.manager.get(workspaceId)?.status, "ready")
+      assert.equal(harness.runtime.active.has(workspaceId), true)
+    })
+  }
+})
diff --git a/packages/server/src/workspaces/manager.ts b/packages/server/src/workspaces/manager.ts
index c497db2d..547bccd8 100644
--- a/packages/server/src/workspaces/manager.ts
+++ b/packages/server/src/workspaces/manager.ts
@@ -1,6 +1,8 @@
 import path from "path"
 import { spawnSync } from "child_process"
+import { randomUUID } from "node:crypto"
 import { connect } from "net"
+import { setTimeout as delay } from "node:timers/promises"
 import { EventBus } from "../events/bus"
 import type { SettingsService } from "../settings/service"
 import type { BinaryResolver } from "../settings/binaries"
@@ -22,8 +24,33 @@ import {
   OPENCODE_SERVER_USERNAME_ENV,
   resolveOpencodeServerAuth,
 } from "./opencode-auth"
+import { resolveWorkspaceIdentity } from "./workspace-identity"
+import { parseWslUncPath } from "./spawn"
 
 const STARTUP_STABILITY_DELAY_MS = 1500
+const DEFAULT_LAUNCH_TIMEOUT_MS = 30_000
+const ORDINARY_CREATION_OWNER = ""
+const WORKSPACE_STATE = Symbol("workspaceState")
+type ManagerTimeout = ReturnType<typeof setTimeout>
+
+interface WorkspaceRuntimeController {
+  launch: WorkspaceRuntime["launch"]
+  stop: WorkspaceRuntime["stop"]
+}
+
+export function binaryPathsEqual(left: string, right: string, platform = process.platform): boolean {
+  const leftWsl = parseWslUncPath(left)
+  const rightWsl = parseWslUncPath(right)
+  if (leftWsl || rightWsl) {
+    return Boolean(
+      leftWsl
+      && rightWsl
+      && leftWsl.distro.toLowerCase() === rightWsl.distro.toLowerCase()
+      && leftWsl.linuxPath === rightWsl.linuxPath,
+    )
+  }
+  return platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right
+}
 
 interface WorkspaceManagerOptions {
   rootDir: string
@@ -34,35 +61,132 @@ interface WorkspaceManagerOptions {
   getServerBaseUrl: () => string
   /** Optional CA bundle path to trust CodeNomad HTTPS certs. */
   nodeExtraCaCertsPath?: string
+  runtime?: Pick<WorkspaceRuntime, "launch" | "stop">
+  shutdownTimeoutMs?: number
+  launchSettlementTimeoutMs?: number
+  launchTimeoutMs?: number
+  setTimeout?: (callback: () => void, delayMs: number) => ManagerTimeout
+  clearTimeout?: (timer: ManagerTimeout) => void
 }
 
-interface WorkspaceRecord extends WorkspaceDescriptor {}
+interface WorkspaceRecord extends WorkspaceDescriptor {
+  identityKey: string
+  ownership: WorkspaceCreationOwnership
+  [WORKSPACE_STATE]: WorkspaceState
+}
 
+interface WorkspaceState {
+  abortController: AbortController
+  creation?: Promise<WorkspaceCreateResult>
+  settlement?: Promise<void>
+  deletePromise?: Promise<WorkspaceDescriptor | undefined>
+  published: boolean
+  stoppedPublished: boolean
+}
+export class WorkspaceLaunchCancelledError extends Error {
+  constructor(workspaceId: string) {
+    super(`Workspace ${workspaceId} launch was cancelled`)
+    this.name = "WorkspaceLaunchCancelledError"
+  }
+}
+export class WorkspaceLaunchTimeoutError extends Error {
+  readonly code = "WORKSPACE_LAUNCH_TIMEOUT"
+  readonly retryable = true
+  constructor(workspaceId: string | undefined, timeoutMs: number) {
+    super(`${workspaceId ? `Workspace ${workspaceId}` : "Workspace"} did not finish launching within ${timeoutMs}ms`)
+    this.name = "WorkspaceLaunchTimeoutError"
+  }
+}
+export class WorkspaceCleanupTimeoutError extends Error {
+  readonly code = "WORKSPACE_CLEANUP_TIMEOUT"
+  readonly retryable = true
+  constructor(operation: string, timeoutMs: number) {
+    super(`Workspace ${operation} did not finish within ${timeoutMs}ms; cleanup can be retried`)
+    this.name = "WorkspaceCleanupTimeoutError"
+  }
+}
+export class WorkspaceShutdownError extends AggregateError {
+  readonly code = "WORKSPACE_SHUTDOWN_FAILED"
+  readonly retryable = true
+  constructor(errors: unknown[]) {
+    super(errors, `Failed to stop ${errors.length} workspace${errors.length === 1 ? "" : "s"} during shutdown; cleanup can be retried`)
+    this.name = "WorkspaceShutdownError"
+  }
+}
+export interface WorkspaceCreateResult {
+  workspace: WorkspaceDescriptor
+  created: boolean
+}
+export interface WorkspaceCreateOptions {
+  binaryPath?: string
+  requestId?: string
+  forceNew?: boolean
+}
+type CreationRequestState = "active" | "cancelled" | "released"
+type WorkspaceCreationOwnership = Map<string, CreationRequestState>
+interface WorkspaceReadiness {
+  workspaceId: string
+  port: number
+  exitPromise: Promise<ProcessExitInfo>
+  getLastOutput: () => string
+  signal?: AbortSignal
+}
 export class WorkspaceManager {
   private readonly workspaces = new Map<string, WorkspaceRecord>()
-  private readonly runtime: WorkspaceRuntime
+  private readonly pendingWorkspaceCreations = new Map<string, WorkspaceRecord>()
+  private readonly cancelledCreationRequests = new Set<string>()
+  private shuttingDown = false
+  private readonly runtime: Pick<WorkspaceRuntime, "launch" | "stop">
   private readonly codeNomadPluginUrl: string
   private readonly opencodeAuth = new Map<string, { username: string; password: string; authorization: string }>()
 
   constructor(private readonly options: WorkspaceManagerOptions) {
-    this.runtime = new WorkspaceRuntime(this.options.eventBus, this.options.logger)
+    this.runtime = options.runtime ?? new WorkspaceRuntime(this.options.eventBus, this.options.logger)
     this.codeNomadPluginUrl = getCodeNomadPluginUrl()
   }
-
   list(): WorkspaceDescriptor[] {
     return Array.from(this.workspaces.values())
+      .filter((record) => record[WORKSPACE_STATE].published)
   }
 
   get(id: string): WorkspaceDescriptor | undefined {
-    return this.workspaces.get(id)
+    const record = this.workspaces.get(id)
+    return record?.[WORKSPACE_STATE].published ? record : undefined
   }
 
   getInstancePort(id: string): number | undefined {
-    return this.workspaces.get(id)?.port
+    const record = this.workspaces.get(id)
+    return record?.[WORKSPACE_STATE].published ? record.port : undefined
   }
 
   getInstanceAuthorizationHeader(id: string): string | undefined {
-    return this.opencodeAuth.get(id)?.authorization
+    return this.workspaces.get(id)?.[WORKSPACE_STATE].published ? this.opencodeAuth.get(id)?.authorization : undefined
+  }
+
+  findReadyInstanceIdByBinary(binaryPath: string): string | undefined {
+    const resolvedPath = this.resolveBinaryPath(binaryPath)
+    return this.list().find((workspace) => {
+      return workspace.status === "ready" && binaryPathsEqual(workspace.binaryId, resolvedPath)
+    })?.id
+  }
+
+  private findReadyWorkspaceByIdentity(
+    identityKey: string,
+    includeRestoreOwned: boolean,
+  ): WorkspaceDescriptor | undefined {
+    for (const record of this.workspaces.values()) {
+      const state = record[WORKSPACE_STATE]
+      if (
+        state.published
+        && !state.abortController.signal.aborted
+        && (includeRestoreOwned || !record.requestId)
+        && record.status === "ready"
+        && record.identityKey === identityKey
+      ) {
+        return record
+      }
+    }
+    return undefined
   }
 
   listFiles(workspaceId: string, relativePath = "."): FileSystemEntry[] {
@@ -114,12 +238,78 @@ export class WorkspaceManager {
     browser.writeFile(relativePath, contents)
   }
 
-  async create(folder: string, name?: string): Promise<WorkspaceDescriptor> {
- 
-    const id = `${Date.now().toString(36)}`
-    const binary = this.options.binaryResolver.resolveDefault()
-    const resolvedBinaryPath = this.resolveBinaryPath(binary.path)
-    const workspacePath = path.isAbsolute(folder) ? folder : path.resolve(this.options.rootDir, folder)
+  async create(
+    folder: string,
+    name?: string,
+    options: WorkspaceCreateOptions = {},
+  ): Promise<WorkspaceCreateResult> {
+    const launchTimeoutMs = Math.max(1, this.options.launchTimeoutMs ?? DEFAULT_LAUNCH_TIMEOUT_MS)
+    const launchDeadlineAt = Date.now() + launchTimeoutMs
+    try {
+      const { workspacePath, identityKey } = await this.withLaunchDeadline(
+        resolveWorkspaceIdentity(folder, this.options.rootDir),
+        undefined,
+        launchDeadlineAt,
+        launchTimeoutMs,
+      )
+      if (options.requestId && this.cancelledCreationRequests.has(options.requestId)) {
+        throw new Error(`Workspace creation request ${options.requestId} was cancelled`)
+      }
+      if (this.shuttingDown) {
+        throw new Error("Workspace manager is shutting down")
+      }
+      if (options.forceNew) {
+        const ownership = this.createOwnership(options.requestId)
+        const record = this.reserveWorkspace(workspacePath, identityKey, name, options, ownership, launchDeadlineAt)
+        const result = await this.startCreation(record, options, launchDeadlineAt, launchTimeoutMs)
+        return this.finishCreation(result, options.requestId, ownership)
+      }
+      const existing = this.findReadyWorkspaceByIdentity(identityKey, Boolean(options.requestId))
+      if (existing) {
+        this.options.logger.info({ workspaceId: existing.id, folder: workspacePath }, "Reusing existing workspace")
+        const record = this.workspaces.get(existing.id)
+        if (options.requestId && record) {
+          if (!record.ownership.has(options.requestId)) record.ownership.set(options.requestId, "active")
+          this.syncOwnership(record)
+          return this.finishCreation({ workspace: existing, created: false }, options.requestId, record.ownership)
+        }
+        return { workspace: existing, created: false }
+      }
+      const pending = this.pendingWorkspaceCreations.get(identityKey)
+      if (pending) {
+        const state = pending[WORKSPACE_STATE]
+        const owner = options.requestId ?? ORDINARY_CREATION_OWNER
+        if (!pending.ownership.has(owner)) pending.ownership.set(owner, "active")
+        this.syncOwnership(pending)
+        const result = await state.creation!
+        return this.finishCreation({ workspace: result.workspace, created: false }, options.requestId, pending.ownership)
+      }
+      const ownership = this.createOwnership(options.requestId)
+      const record = this.reserveWorkspace(workspacePath, identityKey, name, options, ownership, launchDeadlineAt)
+      const creation = this.startCreation(record, options, launchDeadlineAt, launchTimeoutMs)
+      this.pendingWorkspaceCreations.set(identityKey, record)
+      try {
+        return this.finishCreation(await creation, options.requestId, ownership)
+      } finally {
+        if (this.pendingWorkspaceCreations.get(identityKey) === record) {
+          this.pendingWorkspaceCreations.delete(identityKey)
+        }
+      }
+    } finally {
+      if (options.requestId) this.cancelledCreationRequests.delete(options.requestId)
+    }
+  }
+  private reserveWorkspace(
+    workspacePath: string,
+    identityKey: string,
+    name: string | undefined,
+    options: WorkspaceCreateOptions,
+    ownership: WorkspaceCreationOwnership,
+    launchDeadlineAt: number,
+  ): WorkspaceRecord {
+    const id = randomUUID()
+    const binary = this.options.binaryResolver.resolve(options.binaryPath)
+    const resolvedBinaryPath = this.resolveBinaryPath(binary.path, Math.max(1, launchDeadlineAt - Date.now()))
     clearWorkspaceSearchCache(workspacePath)
 
     this.options.logger.info({ workspaceId: id, folder: workspacePath, binary: resolvedBinaryPath }, "Creating workspace")
@@ -127,8 +317,9 @@ export class WorkspaceManager {
     const proxyPath = `/workspaces/${id}/instance`
 
 
-    const descriptor: WorkspaceRecord = {
+    const record = {
       id,
+      requestId: options.requestId,
       path: workspacePath,
       name,
       status: "starting",
@@ -138,137 +329,328 @@ export class WorkspaceManager {
       binaryVersion: binary.version,
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
-    }
-
-    this.workspaces.set(id, descriptor)
-
-
-    this.options.eventBus.publish({ type: "workspace.created", workspace: descriptor })
-
-    const serverConfig = this.options.settings.getOwner("config", "server")
-    const envVars = (serverConfig as any)?.environmentVariables
-    const userEnvironment = envVars && typeof envVars === "object" && !Array.isArray(envVars) ? (envVars as any) : {}
-    const opencodeConfigContent = buildOpencodeConfigContent(
-      resolveExistingOpencodeConfigContent(userEnvironment),
-      this.codeNomadPluginUrl,
-    )
-    const serverBaseUrl = this.options.getServerBaseUrl()
-    const normalizedServerBaseUrl = serverBaseUrl.replace(/\/+$/, "")
-
-    const { username: opencodeUsername, password: opencodePassword } = resolveOpencodeServerAuth({
-      userEnvironment,
-      processEnv: process.env,
+    } as WorkspaceRecord
+    Object.defineProperties(record, {
+      identityKey: { value: identityKey },
+      ownership: { value: ownership },
+      [WORKSPACE_STATE]: { value: { abortController: new AbortController(), published: false, stoppedPublished: false } },
     })
-    const authorization = buildOpencodeBasicAuthHeader({ username: opencodeUsername, password: opencodePassword })
-    if (!authorization) {
-      throw new Error("Failed to build OpenCode auth header")
+
+    this.workspaces.set(id, record)
+    if (options.requestId && this.cancelledCreationRequests.has(options.requestId)) {
+      record[WORKSPACE_STATE].abortController.abort(new WorkspaceLaunchCancelledError(id))
     }
-    this.opencodeAuth.set(id, { username: opencodeUsername, password: opencodePassword, authorization })
-
-    const environment = {
-      ...userEnvironment,
-      OPENCODE_CONFIG_CONTENT: opencodeConfigContent,
-      OPENCODE_EXPERIMENTAL_WORKSPACES: "true",
-      CODENOMAD_INSTANCE_ID: id,
-      CODENOMAD_BASE_URL: serverBaseUrl,
-      ...(this.options.nodeExtraCaCertsPath ? { NODE_EXTRA_CA_CERTS: this.options.nodeExtraCaCertsPath } : {}),
-      [OPENCODE_SERVER_BASE_URL_ENV]: `${normalizedServerBaseUrl}${proxyPath}`,
-      [OPENCODE_SERVER_USERNAME_ENV]: opencodeUsername,
-      [OPENCODE_SERVER_PASSWORD_ENV]: opencodePassword,
-    }
-
-    const logLevel = (serverConfig as any)?.logLevel
-
+    return record
+  }
+  private startCreation(record: WorkspaceRecord, options: WorkspaceCreateOptions,
+    launchDeadlineAt: number, launchTimeoutMs: number): Promise<WorkspaceCreateResult> {
+    const creation = this.createWithDeadline(record, options, launchDeadlineAt, launchTimeoutMs)
+    record[WORKSPACE_STATE].creation = creation
+    record[WORKSPACE_STATE].settlement = creation.then(() => undefined, () => undefined)
+    return creation
+  }
+  private async createWithDeadline(record: WorkspaceRecord, options: WorkspaceCreateOptions,
+    launchDeadlineAt: number, launchTimeoutMs: number): Promise<WorkspaceCreateResult> {
+    const timeoutMs = Math.max(1, launchDeadlineAt - Date.now())
+    const state = record[WORKSPACE_STATE]
+    let timeout: ManagerTimeout | null = (this.options.setTimeout ?? setTimeout)(() => {
+      timeout = null
+      if (!state.abortController.signal.aborted) {
+        state.abortController.abort(new WorkspaceLaunchTimeoutError(record.id, launchTimeoutMs))
+      }
+    }, timeoutMs)
     try {
+      return await this.createResolvedWorkspace(record, options)
+    } finally {
+      if (timeout) (this.options.clearTimeout ?? clearTimeout)(timeout)
+    }
+  }
+
+  private async withLaunchDeadline<T>(operation: Promise<T>, workspaceId: string | undefined,
+    deadlineAt: number, launchTimeoutMs: number): Promise<T> {
+    const timeoutMs = Math.max(1, deadlineAt - Date.now())
+    let timeout: ManagerTimeout | null = null
+    const deadline = new Promise<never>((_resolve, reject) => {
+      timeout = (this.options.setTimeout ?? setTimeout)(() => {
+        timeout = null
+        reject(new WorkspaceLaunchTimeoutError(workspaceId, launchTimeoutMs))
+      }, timeoutMs)
+    })
+    try {
+      return await Promise.race([operation, deadline])
+    } finally {
+      if (timeout) (this.options.clearTimeout ?? clearTimeout)(timeout)
+    }
+  }
+  private async createResolvedWorkspace(
+    record: WorkspaceRecord,
+    options: WorkspaceCreateOptions,
+  ): Promise<WorkspaceCreateResult> {
+    const state = record[WORKSPACE_STATE]
+    const { id, path: workspacePath, binaryId: resolvedBinaryPath, proxyPath } = record
+    try {
+      this.throwIfCancelled(record)
+
+      const serverConfig = this.options.settings.getOwner("config", "server")
+      const envVars = (serverConfig as any)?.environmentVariables
+      const userEnvironment = envVars && typeof envVars === "object" && !Array.isArray(envVars) ? (envVars as any) : {}
+      const opencodeConfigContent = buildOpencodeConfigContent(
+        resolveExistingOpencodeConfigContent(userEnvironment),
+        this.codeNomadPluginUrl,
+      )
+      const serverBaseUrl = this.options.getServerBaseUrl()
+      const normalizedServerBaseUrl = serverBaseUrl.replace(/\/+$/, "")
+
+      const { username: opencodeUsername, password: opencodePassword } = resolveOpencodeServerAuth({
+        userEnvironment,
+        processEnv: process.env,
+      })
+      const authorization = buildOpencodeBasicAuthHeader({ username: opencodeUsername, password: opencodePassword })
+      if (!authorization) {
+        throw new Error("Failed to build OpenCode auth header")
+      }
+      this.opencodeAuth.set(id, { username: opencodeUsername, password: opencodePassword, authorization })
+
+      const environment = {
+        ...userEnvironment,
+        OPENCODE_CONFIG_CONTENT: opencodeConfigContent,
+        OPENCODE_EXPERIMENTAL_WORKSPACES: "true",
+        CODENOMAD_INSTANCE_ID: id,
+        CODENOMAD_BASE_URL: serverBaseUrl,
+        ...(this.options.nodeExtraCaCertsPath ? { NODE_EXTRA_CA_CERTS: this.options.nodeExtraCaCertsPath } : {}),
+        [OPENCODE_SERVER_BASE_URL_ENV]: `${normalizedServerBaseUrl}${proxyPath}`,
+        [OPENCODE_SERVER_USERNAME_ENV]: opencodeUsername,
+        [OPENCODE_SERVER_PASSWORD_ENV]: opencodePassword,
+      }
+
+      const logLevel = (serverConfig as any)?.logLevel
       const { pid, port, exitPromise, getLastOutput } = await this.runtime.launch({
         workspaceId: id,
         folder: workspacePath,
         binaryPath: resolvedBinaryPath,
         environment,
         logLevel,
+        signal: state.abortController.signal,
         onExit: (info) => this.handleProcessExit(info.workspaceId, info),
       })
+      record.pid = pid
+      record.port = port
 
-      const runtimeVersion = await this.waitForWorkspaceReadiness({ workspaceId: id, port, exitPromise, getLastOutput })
+      this.throwIfCancelled(record)
+      state.published = true
+      this.options.eventBus.publish({ type: "workspace.created", workspace: record })
+      this.throwIfCancelled(record)
+      const runtimeVersion = await this.waitForWorkspaceReadiness({
+        workspaceId: id,
+        port,
+        exitPromise,
+        getLastOutput,
+        signal: state.abortController.signal,
+      })
+      this.throwIfCancelled(record)
       if (runtimeVersion) {
-        descriptor.binaryVersion = runtimeVersion
+        record.binaryVersion = runtimeVersion
       }
 
-      descriptor.pid = pid
-      descriptor.port = port
-      descriptor.status = "ready"
-      descriptor.updatedAt = new Date().toISOString()
-      this.options.eventBus.publish({ type: "workspace.started", workspace: descriptor })
+      record.status = "ready"
+      record.updatedAt = new Date().toISOString()
+      this.options.eventBus.publish({ type: "workspace.started", workspace: record })
       this.options.logger.info({ workspaceId: id, port }, "Workspace ready")
-      return descriptor
+      return { workspace: record, created: true }
     } catch (error) {
-      descriptor.status = "error"
-      descriptor.error = error instanceof Error ? error.message : String(error)
-      descriptor.updatedAt = new Date().toISOString()
-      this.options.eventBus.publish({ type: "workspace.error", workspace: descriptor })
-      this.options.logger.error({ workspaceId: id, err: error }, "Workspace failed to start")
-      throw error
+      const launchFailure = state.abortController.signal.aborted ? state.abortController.signal.reason : error
+      let stopFailure: unknown
+      await this.runtime.stop(id).catch((stopError) => {
+        stopFailure = stopError
+      })
+      if (!stopFailure) {
+        this.removeRecord(id, record, state.published)
+        throw launchFailure
+      }
+      if (!state.published) {
+        throw stopFailure
+      }
+      record.status = "error"
+      record.error = stopFailure instanceof Error
+        ? `Workspace startup failed and its process could not be stopped: ${stopFailure.message}`
+        : launchFailure instanceof Error ? launchFailure.message : String(launchFailure)
+      record.updatedAt = new Date().toISOString()
+      if (this.workspaces.get(id) === record && state.published) {
+        this.options.eventBus.publish({ type: "workspace.error", workspace: record })
+      }
+      this.options.logger.error({ workspaceId: id, err: launchFailure }, "Workspace failed to start")
+      throw launchFailure
     }
   }
 
-  async delete(id: string): Promise<WorkspaceDescriptor | undefined> {
-    const workspace = this.workspaces.get(id)
-    if (!workspace) return undefined
-
-    this.options.logger.info({ workspaceId: id }, "Stopping workspace")
-    const wasRunning = Boolean(workspace.pid)
-    if (wasRunning) {
-      await this.runtime.stop(id).catch((error) => {
-        this.options.logger.warn({ workspaceId: id, err: error }, "Failed to stop workspace process cleanly")
+  delete(id: string): Promise<WorkspaceDescriptor | undefined> {
+    const record = this.workspaces.get(id)
+    if (!record) return Promise.resolve(undefined)
+    const state = record[WORKSPACE_STATE]
+    if (!state.abortController.signal.aborted) {
+      state.abortController.abort(new WorkspaceLaunchCancelledError(id))
+    }
+    const pending = this.pendingWorkspaceCreations.get(record.identityKey)
+    if (pending === record) {
+      this.pendingWorkspaceCreations.delete(record.identityKey)
+    }
+    if (!state.deletePromise) {
+      let deletePromise!: Promise<WorkspaceDescriptor | undefined>
+      deletePromise = this.cleanupDeletedWorkspace(id, record).catch((error) => {
+        if (state.deletePromise === deletePromise) state.deletePromise = undefined
+        throw error
       })
+      state.deletePromise = deletePromise
     }
+    return state.deletePromise
+  }
 
-    this.workspaces.delete(id)
-    this.opencodeAuth.delete(id)
-    clearWorkspaceSearchCache(workspace.path)
-    if (!wasRunning) {
-      this.options.eventBus.publish({ type: "workspace.stopped", workspaceId: id })
+  releaseCreationRequest(id: string, requestId: string): boolean {
+    const record = this.workspaces.get(id)
+    if (!record?.[WORKSPACE_STATE].published) return false
+    const ownership = record.ownership
+    const state = ownership.get(requestId)
+    if (state === "released") return true
+    if (state === "cancelled") return false
+    if (state !== "active") return false
+    ownership.set(requestId, "released")
+    this.syncOwnership(record)
+    return true
+  }
+
+  async cancelCreationRequest(requestId: string): Promise<void> {
+    let matched = false
+    for (const [workspaceId, record] of this.workspaces) {
+      const ownership = record.ownership
+      const state = ownership.get(requestId)
+      if (state === "released") { matched = true; continue }
+      if (state === "cancelled") {
+        matched = true
+        if (this.hasActiveRequest(ownership) || this.isRetained(ownership)) continue
+        await this.delete(workspaceId)
+        return
+      }
+      if (state !== "active") continue
+      matched = true
+      ownership.set(requestId, "cancelled")
+      this.syncOwnership(record)
+      if (this.hasActiveRequest(ownership) || this.isRetained(ownership)) return
+      await this.delete(workspaceId)
+      return
     }
-    return workspace
+    if (!matched) this.cancelledCreationRequests.add(requestId)
+  }
+
+  private createOwnership(requestId?: string): WorkspaceCreationOwnership {
+    return new Map([[requestId ?? ORDINARY_CREATION_OWNER, "active"]])
+  }
+
+  private finishCreation(
+    result: WorkspaceCreateResult,
+    requestId: string | undefined,
+    ownership: WorkspaceCreationOwnership,
+  ): WorkspaceCreateResult {
+    if (requestId && ownership.get(requestId) === "cancelled") {
+      throw new Error(`Workspace creation request ${requestId} was cancelled`)
+    }
+    const retained = this.isRetained(ownership)
+    return {
+      workspace: requestId ? { ...result.workspace, requestId } : result.workspace,
+      created: result.created && !(requestId && retained),
+    }
+  }
+
+  private syncOwnership(record: WorkspaceRecord | undefined): void {
+    if (!record) return
+    const ownership = record.ownership
+    record.requestId = this.isRetained(ownership)
+      ? undefined
+      : Array.from(ownership).find(([, state]) => state === "active")?.[0]
+  }
+
+  private isRetained(ownership: WorkspaceCreationOwnership): boolean {
+    return ownership.has(ORDINARY_CREATION_OWNER) || Array.from(ownership.values()).includes("released")
+  }
+
+  private hasActiveRequest(ownership: WorkspaceCreationOwnership): boolean {
+    return Array.from(ownership).some(([requestId, state]) => Boolean(requestId) && state === "active")
   }
 
   async shutdown() {
+    this.shuttingDown = true
     this.options.logger.info("Shutting down all workspaces")
-
-    const stopTasks: Array<Promise<void>> = []
-
-    for (const [id, workspace] of this.workspaces) {
-      if (!workspace.pid) {
-        this.options.logger.debug({ workspaceId: id }, "Workspace already stopped")
-        continue
-      }
-
-      this.options.logger.info({ workspaceId: id }, "Stopping workspace during shutdown")
-      stopTasks.push(
-        this.runtime.stop(id).catch((error) => {
-          this.options.logger.error({ workspaceId: id, err: error }, "Failed to stop workspace during shutdown")
-        }),
-      )
-    }
-
-    if (stopTasks.length > 0) {
-      await Promise.allSettled(stopTasks)
-    }
-
-    this.workspaces.clear()
-    this.opencodeAuth.clear()
-    this.options.logger.info("All workspaces cleared")
+    const stopTasks = Array.from(this.workspaces.keys(), (id) => this.delete(id))
+    const results = stopTasks.length
+      ? await this.withTimeout(Promise.allSettled(stopTasks), this.options.shutdownTimeoutMs ?? 10000, "shutdown")
+      : []
+    const stopFailures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : [])
+    if (this.workspaces.size === 0) {
+      this.pendingWorkspaceCreations.clear()
+      this.cancelledCreationRequests.clear()
+    } else if (!stopFailures.length) stopFailures.push(
+      new Error(`Workspace cleanup remains incomplete for: ${Array.from(this.workspaces.keys()).join(", ")}`),
+    )
+    if (stopFailures.length) throw new WorkspaceShutdownError(stopFailures)
   }
 
-  private requireWorkspace(id: string): WorkspaceRecord {
-    const workspace = this.workspaces.get(id)
-    if (!workspace) {
-      throw new Error("Workspace not found")
+  private async withTimeout<T>(operation: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+    let timeout: ManagerTimeout | null = null
+    const deadline = new Promise<never>((_resolve, reject) => {
+      timeout = (this.options.setTimeout ?? setTimeout)(() => {
+        timeout = null
+        reject(new WorkspaceCleanupTimeoutError(label, timeoutMs))
+      }, timeoutMs)
+    })
+
+    try {
+      return await Promise.race([operation, deadline])
+    } finally {
+      if (timeout) (this.options.clearTimeout ?? clearTimeout)(timeout)
     }
-    return workspace
   }
 
-  private resolveBinaryPath(identifier: string): string {
+  private requireWorkspace(id: string): WorkspaceDescriptor {
+    const record = this.workspaces.get(id)
+    if (!record?.[WORKSPACE_STATE].published) throw new Error("Workspace not found")
+    return record
+  }
+
+  private throwIfCancelled(record: WorkspaceRecord): void {
+    record[WORKSPACE_STATE].abortController.signal.throwIfAborted()
+  }
+
+  private async cleanupDeletedWorkspace(id: string, record: WorkspaceRecord): Promise<WorkspaceDescriptor> {
+    // Stop once immediately, then again after launch settlement to cover a child
+    // that became available while cancellation was propagating.
+    const immediateStop = this.runtime.stop(id).catch((error) => {
+      this.options.logger.warn({ workspaceId: id, err: error }, "Initial workspace process cleanup failed; retrying after launch settles")
+    })
+    await this.withTimeout(record[WORKSPACE_STATE].settlement!, this.options.launchSettlementTimeoutMs ?? 5000, `${id} launch cancellation`)
+    await immediateStop
+    await this.runtime.stop(id)
+
+    this.removeRecord(id, record, true)
+    return record
+  }
+
+  private removeRecord(id: string, record: WorkspaceRecord, publishStopped: boolean): void {
+    if (this.workspaces.get(id) !== record) return
+    this.workspaces.delete(id)
+    this.opencodeAuth.delete(id)
+    clearWorkspaceSearchCache(record.path)
+    if (publishStopped) this.publishStopped(record, "deleted")
+  }
+
+  private publishStopped(record: WorkspaceRecord, reason: "deleted" | "stopped" = "stopped"): void {
+    const state = record[WORKSPACE_STATE]
+    if (!state.published || state.stoppedPublished) return
+    state.stoppedPublished = true
+    record.status = "stopped"
+    record.error = undefined
+    this.options.eventBus.publish({ type: "workspace.stopped", workspaceId: record.id, reason })
+  }
+
+  resolveBinaryPath(identifier: string, timeoutMs = DEFAULT_LAUNCH_TIMEOUT_MS): string {
     if (!identifier) {
       return identifier
     }
@@ -281,7 +663,7 @@ export class WorkspaceManager {
     const locator = process.platform === "win32" ? "where" : "which"
 
     try {
-      const result = spawnSync(locator, [identifier], { encoding: "utf8" })
+      const result = spawnSync(locator, [identifier], { encoding: "utf8", timeout: Math.max(1, timeoutMs) })
       if (result.status === 0 && result.stdout) {
         const candidates = result.stdout
           .split(/\r?\n/)
@@ -321,58 +703,27 @@ export class WorkspaceManager {
     return candidates[0] ?? ""
   }
 
-  private async waitForWorkspaceReadiness(params: {
-    workspaceId: string
-    port: number
-    exitPromise: Promise<ProcessExitInfo>
-    getLastOutput: () => string
-  }): Promise<string | undefined> {
+  private async waitForWorkspaceReadiness(params: WorkspaceReadiness): Promise<string | undefined> {
 
     await Promise.race([
-      this.waitForPortAvailability(params.port),
-      params.exitPromise.then((info) => {
-        throw this.buildStartupError(
-          params.workspaceId,
-          "exited before becoming ready",
-          info,
-          params.getLastOutput(),
-        )
-      }),
+      this.waitForPortAvailability(params.port, 5000, params.signal),
+      this.exitDuringStartup(params, "exited before becoming ready"),
     ])
 
     const version = await this.waitForInstanceHealth(params)
 
     await Promise.race([
-      this.delay(STARTUP_STABILITY_DELAY_MS),
-      params.exitPromise.then((info) => {
-        throw this.buildStartupError(
-          params.workspaceId,
-          "exited shortly after start",
-          info,
-          params.getLastOutput(),
-        )
-      }),
+      delay(STARTUP_STABILITY_DELAY_MS, undefined, { signal: params.signal }),
+      this.exitDuringStartup(params, "exited shortly after start"),
     ])
 
     return version
   }
 
-  private async waitForInstanceHealth(params: {
-    workspaceId: string
-    port: number
-    exitPromise: Promise<ProcessExitInfo>
-    getLastOutput: () => string
-  }): Promise<string | undefined> {
+  private async waitForInstanceHealth(params: WorkspaceReadiness): Promise<string | undefined> {
     const probeResult = await Promise.race([
-      this.probeInstance(params.workspaceId, params.port),
-      params.exitPromise.then((info) => {
-        throw this.buildStartupError(
-          params.workspaceId,
-          "exited during health checks",
-          info,
-          params.getLastOutput(),
-        )
-      }),
+      this.probeInstance(params.workspaceId, params.port, params.signal),
+      this.exitDuringStartup(params, "exited during health checks"),
     ])
 
     if (probeResult.ok) {
@@ -387,9 +738,16 @@ export class WorkspaceManager {
     throw new Error(`Workspace ${params.workspaceId} failed health check: ${reason}.`)
   }
 
+  private exitDuringStartup(params: WorkspaceReadiness, phase: string): Promise<never> {
+    return params.exitPromise.then((info) => {
+      throw this.buildStartupError(params.workspaceId, phase, info, params.getLastOutput())
+    })
+  }
+
   private async probeInstance(
     workspaceId: string,
     port: number,
+    signal?: AbortSignal,
   ): Promise<{ ok: boolean; reason?: string; version?: string }> {
     const url = `http://127.0.0.1:${port}/global/health`
 
@@ -400,7 +758,7 @@ export class WorkspaceManager {
         headers["Authorization"] = authHeader
       }
 
-      const response = await fetch(url, { headers })
+      const response = await fetch(url, { headers, signal })
       if (!response.ok) {
         const reason = `/global/health returned HTTP ${response.status}`
         this.options.logger.debug({ workspaceId, status: response.status }, "Health probe returned server error")
@@ -437,7 +795,7 @@ export class WorkspaceManager {
     return new Error(`Workspace ${workspaceId} ${phase} (${exitDetails}).${outputDetails}`)
   }
 
-  private waitForPortAvailability(port: number, timeoutMs = 5000): Promise<void> {
+  private waitForPortAvailability(port: number, timeoutMs = 5000, signal?: AbortSignal): Promise<void> {
     return new Promise((resolve, reject) => {
       const deadline = Date.now() + timeoutMs
       let settled = false
@@ -452,17 +810,18 @@ export class WorkspaceManager {
       }
 
       const tryConnect = () => {
-        if (settled) {
-          return
-        }
-        const socket = connect({ port, host: "127.0.0.1" }, () => {
+        if (settled) return
+        const socket = connect({ port, host: "127.0.0.1", signal }, () => {
           cleanup()
           socket.end()
           resolve()
         })
         socket.once("error", () => {
           socket.destroy()
-          if (settled) {
+          if (settled) return
+          if (signal?.aborted) {
+            cleanup()
+            reject(signal.reason)
             return
           }
           if (Date.now() >= deadline) {
@@ -477,17 +836,11 @@ export class WorkspaceManager {
         })
       }
 
+      if (signal?.aborted) return reject(signal.reason)
       tryConnect()
     })
   }
 
-  private delay(durationMs: number): Promise<void> {
-    if (durationMs <= 0) {
-      return Promise.resolve()
-    }
-    return new Promise((resolve) => setTimeout(resolve, durationMs))
-  }
-
   private describeExit(info: ProcessExitInfo): string {
     if (info.signal) {
       return `signal ${info.signal}`
@@ -499,8 +852,9 @@ export class WorkspaceManager {
   }
 
   private handleProcessExit(workspaceId: string, info: { code: number | null; requested: boolean }) {
-    const workspace = this.workspaces.get(workspaceId)
-    if (!workspace) return
+    const record = this.workspaces.get(workspaceId)
+    if (!record) return
+    const workspace = record
 
     this.opencodeAuth.delete(workspaceId)
 
@@ -510,10 +864,8 @@ export class WorkspaceManager {
     workspace.port = undefined
     workspace.updatedAt = new Date().toISOString()
 
-    if (info.requested || info.code === 0) {
-      workspace.status = "stopped"
-      workspace.error = undefined
-      this.options.eventBus.publish({ type: "workspace.stopped", workspaceId })
+    if (record[WORKSPACE_STATE].abortController.signal.aborted || info.requested || info.code === 0) {
+      this.publishStopped(record)
     } else {
       workspace.status = "error"
       workspace.error = `Process exited with code ${info.code}`
diff --git a/packages/server/src/workspaces/process-identity.darwin.test.ts b/packages/server/src/workspaces/process-identity.darwin.test.ts
new file mode 100644
index 00000000..f657474f
--- /dev/null
+++ b/packages/server/src/workspaces/process-identity.darwin.test.ts
@@ -0,0 +1,97 @@
+import assert from "node:assert/strict"
+import { spawn, spawnSync } from "node:child_process"
+import { once } from "node:events"
+import { setTimeout as delay } from "node:timers/promises"
+import { it } from "node:test"
+
+import {
+  LAUNCH_CLEANUP_TOKEN_ENV,
+  probePosixProcesses,
+  signalOwnedPosixProcessGroup,
+  signalPosixProcesses,
+} from "./process-identity"
+
+const darwinOnly = { skip: process.platform !== "darwin", timeout: 10_000 }
+
+async function spawnDetachedGroup(cleanupToken?: string) {
+  const leader = spawn(process.execPath, ["-e", `
+    const { spawn } = require("node:child_process")
+    spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], { stdio: "ignore" })
+    process.stdout.write("ready\\n")
+    setInterval(() => {}, 1000)
+  `], {
+    detached: true,
+    stdio: ["ignore", "pipe", "ignore"],
+    env: { ...process.env, ...(cleanupToken ? { [LAUNCH_CLEANUP_TOKEN_ENV]: cleanupToken } : {}) },
+  })
+  assert.ok(leader.pid)
+  await once(leader.stdout!, "data")
+  return leader as typeof leader & { pid: number }
+}
+
+async function assertGroupGone(groupId: number): Promise<void> {
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const remaining = probePosixProcesses(spawnSync, 1_000, "darwin", { groupId })
+    if (remaining.ok && remaining.processes.size === 0) return
+    await delay(50)
+  }
+  assert.fail("owned Darwin process group remained alive after signaling")
+}
+
+it("uses real Darwin ps identities to stop an owned detached process group", darwinOnly, async () => {
+  const leader = await spawnDetachedGroup()
+
+  try {
+    const snapshot = probePosixProcesses(spawnSync, 1_000, "darwin", {
+      pids: [leader.pid],
+      groupId: leader.pid,
+    })
+    assert.equal(snapshot.ok, true)
+    assert.equal(snapshot.ok && snapshot.processes.get(leader.pid)?.groupId, leader.pid)
+    assert.equal(snapshot.ok && snapshot.processes.size >= 2, true)
+
+    const signaled = signalOwnedPosixProcessGroup(spawnSync, leader.pid, "SIGTERM", 1_000)
+    assert.equal(signaled.ok && signaled.matched, true)
+    assert.equal(signaled.ok && signaled.signalSent, true)
+    await assertGroupGone(leader.pid)
+  } finally {
+    try {
+      process.kill(-leader.pid, "SIGKILL")
+    } catch {
+      // The successful path has already removed the process group.
+    }
+  }
+})
+
+it("uses a retained real Darwin identity anchor after the group leader exits", darwinOnly, async () => {
+  const cleanupToken = "darwin-integration-cleanup-token"
+  const leader = await spawnDetachedGroup(cleanupToken)
+
+  try {
+    const snapshot = probePosixProcesses(spawnSync, 1_000, "darwin", { groupId: leader.pid })
+    assert.equal(snapshot.ok, true)
+    const leaderIdentity = snapshot.ok ? snapshot.processes.get(leader.pid) : undefined
+    assert.ok(leaderIdentity)
+    assert.equal(snapshot.ok && snapshot.processes.size >= 2, true)
+
+    leader.kill("SIGTERM")
+    if (leader.exitCode === null) await once(leader, "exit")
+    const signaled = signalPosixProcesses(spawnSync, {
+      leader: leaderIdentity,
+      groupId: leader.pid,
+      members: [],
+      signal: "SIGTERM",
+      allowLeaderlessGroup: true,
+      cleanupToken,
+    }, 1_000, "darwin")
+    assert.equal(signaled.ok && signaled.matched, true)
+    assert.equal(signaled.ok && signaled.signalSent, true)
+    await assertGroupGone(leader.pid)
+  } finally {
+    try {
+      process.kill(-leader.pid, "SIGKILL")
+    } catch {
+      // The successful path has already removed the process group.
+    }
+  }
+})
diff --git a/packages/server/src/workspaces/process-identity.test.ts b/packages/server/src/workspaces/process-identity.test.ts
new file mode 100644
index 00000000..0efe5add
--- /dev/null
+++ b/packages/server/src/workspaces/process-identity.test.ts
@@ -0,0 +1,162 @@
+import assert from "node:assert/strict"
+import { spawn as spawnChild, spawnSync, type SpawnSyncReturns } from "node:child_process"
+import { once } from "node:events"
+import { readFileSync } from "node:fs"
+import { describe, it } from "node:test"
+
+import {
+  probePosixProcesses, probeWindowsProcesses, probeWslProcesses, sameProcess,
+  signalOwnedPosixProcessGroup, signalPosixProcesses, signalWindowsProcesses,
+  startedNoLaterThan, type ProcessIdentity,
+} from "./process-identity"
+
+type Spawn = typeof import("node:child_process").spawnSync
+type Call = { command: string; args: readonly string[]; script: string }
+const output = (stdout = "", status = 0, stderr = ""): SpawnSyncReturns<string> =>
+  ({ pid: 1, output: [null, stdout, stderr], stdout, stderr, status, signal: null })
+const spawn = (stdout: string, call?: Call, status = 0, stderr = "") => ((command: string, args: readonly string[]) => {
+  if (call) Object.assign(call, { command, args, script: command === "powershell.exe" ? args.at(-1) ?? "" : args[args.indexOf("-c") + 1] ?? "" })
+  return output(stdout, status, stderr)
+}) as unknown as Spawn
+const b64 = (value: string) => Buffer.from(value).toString("base64")
+const identity = (startTime = "123456"): ProcessIdentity =>
+  ({ pid: 42, parentPid: 1, groupId: 42, startTime, bootId: "boot-a", startOrder: startTime })
+
+describe("process identity probes", () => {
+  it("parses immutable Linux identities", () => {
+    const call = {} as Call
+    const probe = probePosixProcesses(spawn("42|1|42|123456|boot-a|123456\n", call), 25, "linux")
+    assert.deepEqual([call.command, call.args.includes("codenomad-posix-identity"), call.script.trimEnd().endsWith("exit 0")], ["sh", true, true])
+    assert.deepEqual(probe.ok && probe.processes.get(42), identity())
+  })
+
+  it("queries the requested Linux launch group without per-process subprocesses", () => {
+    const call = {} as Call
+    const probe = probePosixProcesses(spawn("42|1|42|123456|boot-a|123456\n", call), 25, "linux", { pids: [42], groupId: 42 })
+    assert.deepEqual(call.args.slice(-1), ["42"])
+    assert.match(call.script, /expected_group=\$stat_group/)
+    assert.doesNotMatch(call.script, /\b(?:cat|cut|sed|basename|dirname)\b/)
+    assert.deepEqual(probe.ok && probe.processes.get(42), identity())
+  })
+
+  it("captures real Linux start ticks and launch-group members within the deadline", { skip: process.platform !== "linux" }, async () => {
+    const child = spawnChild("sh", ["-c", "sleep 5"], { stdio: "ignore" })
+    await once(child, "spawn")
+    try {
+      const stat = readFileSync(`/proc/${process.pid}/stat`, "utf8")
+      const expectedStart = stat.slice(stat.lastIndexOf(") ") + 2).split(" ")[19]
+      const probe = probePosixProcesses(spawnSync, 1_000, "linux", { pids: [process.pid], groupId: process.pid })
+      assert.equal(probe.ok && probe.processes.get(process.pid)?.startTime, expectedStart)
+      assert.equal(probe.ok && probe.processes.has(child.pid!), true)
+    } finally {
+      if (child.exitCode === null && child.signalCode === null) {
+        const exited = once(child, "exit")
+        child.kill()
+        await exited
+      }
+    }
+  })
+
+  it("uses one delimiter-safe process-table query on portable POSIX", () => {
+    const call = {} as Call
+    const command = "/opt/opencode 'pipe|value'\t\"quoted\" café"
+    const start = "Fri Jul 10 12:34:56 2026"
+    const probe = probePosixProcesses(spawn(`42 1 42 ${start} ${command}\n`, call), 25, "darwin")
+    assert.deepEqual([call.command, call.args], ["ps", ["-axo", "pid=,ppid=,pgid=,lstart=,comm="]])
+    assert.equal(probe.ok && probe.processes.get(42)?.startTime, `${start}\t${command}`)
+  })
+
+  it("ignores malformed unrelated portable rows but fails for a malformed requested identity", () => {
+    const start = "Fri Jul 10 12:34:56 2026"
+    const unrelated = `77 1 77 malformed identity\n42 1 42 ${start} opencode\n`
+    const filtered = probePosixProcesses(spawn(unrelated), 25, "darwin", { pids: [42], groupId: 42 })
+    assert.equal(filtered.ok && filtered.processes.get(42)?.startTime, `${start}\topencode`)
+    assert.equal(probePosixProcesses(spawn(unrelated), 25, "darwin", { pids: [77] }).ok, false)
+  })
+
+  it("preserves delimiter-heavy identities through POSIX escalation and rescan", () => {
+    const command = "/opt/opencode pipe|value\nnext\t'quoted'"
+    const row = `CODENOMAD_TARGET_B64|42|1|42|${b64("Fri Jul 10 12:34:56 2026")}|${b64(command)}\nCODENOMAD_RESULT|1||1\n`
+    const expected = `Fri Jul 10 12:34:56 2026\t${command}`
+    const guardedCall = {} as Call
+    const guarded = signalPosixProcesses(spawn(row, guardedCall), { leader: identity(expected), groupId: 42, members: [identity(expected)], signal: "SIGKILL" }, 25, "darwin")
+    const call = {} as Call
+    const owned = signalOwnedPosixProcessGroup(spawn(row, call), 42, "SIGTERM", 25)
+    assert.deepEqual([guarded.ok, guarded.ok && guarded.signaled[0]?.startTime], [true, expected])
+    assert.deepEqual([owned.ok && owned.matched, owned.ok && owned.signaled[0]?.startTime], [true, expected])
+    assert.ok(call.script.indexOf('kill "-$requested_signal"') < call.script.lastIndexOf("for current_pid"))
+    assert.match(call.script, /group_pids\(\).*pid=,pgid=/)
+    assert.doesNotMatch(call.script, /ps -eo pid=/)
+    assert.match(guardedCall.script, /test "\$current_group" = "\$expected_group"/)
+  })
+
+  it("marks a retained portable group request for leaderless guarded cleanup", () => {
+    const call = {} as Call
+    const guarded = signalPosixProcesses(spawn("CODENOMAD_RESULT|1||1\n", call), {
+      leader: identity("gone"), groupId: 42, members: [identity("member")], signal: "SIGTERM",
+      allowLeaderlessGroup: true, cleanupToken: "secret-token",
+    }, 25, "darwin")
+    assert.equal(guarded.ok, true)
+    assert.equal(call.args[7], "1")
+    assert.equal(call.args[8], "secret-token")
+    assert.match(call.script, /anchor=0/)
+    assert.match(call.script, /has_cleanup_token/)
+  })
+
+  it("queries WSL identities in the selected distro", () => {
+    const call = {} as Call
+    const probe = probeWslProcesses(spawn("99|1|99|123456|boot-a|123456\n101|99|99|123460|boot-a|123460\n", call), "Ubuntu Test", 25)
+    assert.deepEqual([call.command, call.args.slice(0, 4), call.args.includes("codenomad-wsl-identity"), call.script.trimEnd().endsWith("exit 0")],
+      ["wsl.exe", ["--distribution", "Ubuntu Test", "--exec", "sh"], true, true])
+    assert.equal(probe.ok && probe.processes.get(101)?.startTime, "123460")
+  })
+
+  it("uses Windows CIM CreationDate as the immutable identity", () => {
+    const call = {} as Call
+    const probe = probeWindowsProcesses(spawn("4242|100|0|20260710123456.123456+000||20260710123456\n", call), 25)
+    assert.match(call.script, /Get-CimInstance Win32_Process/)
+    assert.match(call.script, /ProcessId -gt 0/)
+    assert.equal(probe.ok && probe.processes.get(4242)?.startTime, "20260710123456.123456+000")
+  })
+
+  it("rejects PID reuse and invalid start ordering", () => {
+    const original = identity("9")
+    for (const [candidate, expected] of [[{ ...original }, true], [{ ...original, startTime: "10" }, false], [{ ...original, pid: 43 }, false]] as const)
+      assert.equal(sameProcess(original, candidate), expected)
+    assert.equal(startedNoLaterThan(original, "10"), true)
+    assert.equal(startedNoLaterThan({ ...original, startOrder: "11" }, "10"), false)
+    assert.equal(startedNoLaterThan({ ...original, startOrder: "Fri Jul 10" }, "10"), false)
+  })
+
+  it("returns a POSIX mismatch without a second signal command", () => {
+    const call = {} as Call
+    const guarded = signalPosixProcesses(spawn("CODENOMAD_RESULT|0||0\n", call), { leader: identity(), groupId: 42, members: [identity()], signal: "SIGTERM" }, 25, "linux")
+    assert.deepEqual(guarded, { ok: true, matched: false, signalSent: false, signaled: [] })
+    assert.deepEqual([call.command, call.args[2], call.args.includes("123456")], ["sh", "codenomad-guarded-signal", true])
+    assert.ok(call.script.indexOf('kill "-$requested_signal"') < call.script.indexOf("uptime=$(cut"))
+  })
+
+  it("selects and terminates Windows identities in one guarded CIM invocation", () => {
+    const call = {} as Call
+    const guarded = signalWindowsProcesses(spawn("CODENOMAD_TARGET|4242|1|0|created||99\nCODENOMAD_RESULT|1||1\n", call), { leader: identity("created"), groupId: 42, members: [identity("created")], signal: "SIGKILL" }, 25)
+    assert.equal(guarded.ok && guarded.matched, true)
+    assert.equal(call.command, "powershell.exe")
+    assert.match(call.script, /CreationDate.*Invoke-CimMethod -InputObject/s)
+    assert.equal(call.script.match(/foreach \(\$process in \$selected\)/g)?.length, 2)
+    assert.ok(call.script.indexOf("CODENOMAD_TARGET|") < call.script.indexOf("Invoke-CimMethod"))
+    assert.doesNotMatch(call.script, /taskkill/i)
+  })
+
+  it("retains observed Windows identities after partial termination failure", () => {
+    const rows = "CODENOMAD_TARGET|4242|1|0|created||99\nCODENOMAD_TARGET|4243|4242|0|descendant||100"
+    const guarded = signalWindowsProcesses(spawn(rows, undefined, 1, "termination failed"), { leader: identity("created"), groupId: 42, members: [identity("created")], signal: "SIGTERM" }, 25)
+    assert.equal(guarded.ok, false)
+    assert.deepEqual(!guarded.ok && guarded.observed?.map(({ pid }) => pid), [4242, 4243])
+  })
+
+  it("fails conservatively for command, malformed, and empty probe output", () => {
+    assert.deepEqual(probeWindowsProcesses(spawn("", undefined, 1, "CIM unavailable"), 25), { ok: false, error: "CIM unavailable" })
+    assert.deepEqual(probePosixProcesses(spawn("", undefined, 20, "proc unavailable"), 25, "linux"), { ok: false, error: "proc unavailable" })
+    for (const probe of [probePosixProcesses(spawn("42 malformed process row\n"), 25, "darwin"), probeWslProcesses(spawn("not an identity"), "Ubuntu", 25)]) assert.equal(probe.ok, false)
+  })
+})
diff --git a/packages/server/src/workspaces/process-identity.ts b/packages/server/src/workspaces/process-identity.ts
new file mode 100644
index 00000000..2d9b2f07
--- /dev/null
+++ b/packages/server/src/workspaces/process-identity.ts
@@ -0,0 +1,561 @@
+import type { SpawnSyncReturns, spawnSync } from "node:child_process"
+
+export interface ProcessIdentity {
+  pid: number
+  parentPid: number
+  groupId: number
+  startTime: string
+  bootId?: string
+  startOrder?: string
+}
+
+export type ProcessSnapshot =
+  | { ok: true; processes: Map<number, ProcessIdentity> }
+  | { ok: false; error: string }
+
+export interface GuardedSignalRequest {
+  leader?: ProcessIdentity
+  groupId?: number
+  members: ProcessIdentity[]
+  signal: NodeJS.Signals
+  allowLeaderlessGroup?: boolean
+  cleanupToken?: string
+}
+
+export interface PosixProcessFilter {
+  pids?: readonly number[]
+  groupId?: number
+}
+
+export type GuardedSignalResult =
+  | { ok: true; matched: boolean; signalSent: boolean; signaled: ProcessIdentity[]; cutoff?: string }
+  | { ok: false; error: string; observed?: ProcessIdentity[] }
+
+export type TokenSignalResult = { ok: boolean; signalSent: boolean; targets: ProcessIdentity[]; error?: string }
+
+export const LAUNCH_CLEANUP_TOKEN_ENV = "CODENOMAD_LAUNCH_CLEANUP_TOKEN"
+
+type SpawnCommand = typeof spawnSync
+const SHELL_DOLLAR = "$"
+
+const LINUX_IDENTITY_FUNCTIONS = String.raw`
+IFS= read -r boot 2>/dev/null < /proc/sys/kernel/random/boot_id || exit 20
+read_stat() {
+  line=
+  while IFS= read -r chunk || test -n "$chunk"; do line=$line$chunk; done 2>/dev/null < "/proc/$1/stat"
+  test -n "$line" || return 1
+  stat_pid=$1; rest=${SHELL_DOLLAR}{line##*) }; set -- $rest
+  test "$#" -ge 20 || return 1
+  stat_ppid=$2; stat_group=$3; shift 19; stat_start=$1
+}
+emit_linux() {
+  test -n "$1" && printf '%s|' "$1"
+  printf '%s|%s|%s|%s|%s|%s\n' "$stat_pid" "$stat_ppid" "$stat_group" "$stat_start" "$boot" "$stat_start"
+}
+`
+
+const LINUX_SNAPSHOT_SCRIPT = String.raw`${LINUX_IDENTITY_FUNCTIONS}
+for stat in /proc/[0-9]*/stat; do
+  directory=${SHELL_DOLLAR}{stat%/stat}; pid=${SHELL_DOLLAR}{directory##*/}; read_stat "$pid" && emit_linux ""
+done
+exit 0
+`
+
+const LINUX_LAUNCH_GROUP_SNAPSHOT_SCRIPT = String.raw`${LINUX_IDENTITY_FUNCTIONS}
+leader_pid=$1; read_stat "$leader_pid" || exit 22; expected_group=$stat_group; emit_linux ""
+for stat in /proc/[0-9]*/stat; do
+  directory=${SHELL_DOLLAR}{stat%/stat}; pid=${SHELL_DOLLAR}{directory##*/}; test "$pid" = "$leader_pid" && continue
+  read_stat "$pid" && test "$stat_group" = "$expected_group" && emit_linux ""
+done
+exit 0
+`
+
+const LINUX_GUARDED_SIGNAL_SCRIPT = String.raw`${LINUX_IDENTITY_FUNCTIONS}
+leader_pid=$1; leader_start=$2; leader_boot=$3; expected_group=$4; requested_signal=$5
+shift 5; matched=0; cutoff=; signal_sent=0
+if read_stat "$leader_pid" && test "$boot" = "$leader_boot" && test "$stat_start" = "$leader_start" && test "$stat_group" = "$expected_group"; then
+  matched=1
+  for stat in /proc/[0-9]*/stat; do
+    directory=${SHELL_DOLLAR}{stat%/stat}; candidate=${SHELL_DOLLAR}{directory##*/}; read_stat "$candidate" && test "$stat_group" = "$expected_group" && emit_linux CODENOMAD_TARGET
+  done
+  if kill "-$requested_signal" -- "-$expected_group" 2>/dev/null; then
+    signal_sent=1
+    hz=$(getconf CLK_TCK 2>/dev/null) || exit 21
+    uptime=$(cut -d' ' -f1 /proc/uptime 2>/dev/null) || exit 21
+    cutoff=$(awk -v uptime="$uptime" -v hz="$hz" 'BEGIN { printf "%.0f", uptime * hz }')
+  fi
+else
+  while test "$#" -ge 3; do
+    expected_pid=$1; expected_start=$2; expected_boot=$3; shift 3
+    if read_stat "$expected_pid" && test "$boot" = "$expected_boot" && test "$stat_start" = "$expected_start"; then
+      emit_linux CODENOMAD_TARGET
+      if kill "-$requested_signal" "$expected_pid" 2>/dev/null; then signal_sent=1; fi
+    fi
+  done
+fi
+printf 'CODENOMAD_RESULT|%s|%s|%s\n' "$matched" "$cutoff" "$signal_sent"
+`
+
+const POSIX_IDENTITY_FUNCTIONS = String.raw`
+LC_ALL=C; export LC_ALL; set -f
+encode() { printf '%s' "$1" | base64 | tr -d '\r\n'; }
+read_identity() {
+  current_meta=$(ps -p "$1" -o ppid= -o pgid= -o lstart= -o comm= 2>/dev/null) || return 1
+  current_verify=$(ps -p "$1" -o ppid= -o pgid= -o lstart= -o comm= 2>/dev/null) || return 1
+  test "$current_meta" = "$current_verify" || return 1
+  set -- $current_meta; test "$#" -ge 7 || return 1
+  current_ppid=$1; current_group=$2; shift 2; current_start="$1 $2 $3 $4 $5"
+  shift 5; current_command="$*"; test -n "$current_command" || return 1
+  current_identity=$(printf '%s\t%s' "$current_start" "$current_command")
+}
+emit_target() {
+  printf 'CODENOMAD_TARGET_B64|%s|%s|%s|' "$current_pid" "$current_ppid" "$current_group"
+  encode "$current_start"; printf '|'; encode "$current_command"; printf '\n'
+}
+group_pids() { ps -axo pid=,pgid= 2>/dev/null | awk -v group="$1" '$2 == group { print $1 }'; }
+has_cleanup_token() {
+  test -n "$cleanup_token" || return 1
+  ps eww -p "$1" -o command= 2>/dev/null | tr ' ' '\n' | grep -Fqx -- "${LAUNCH_CLEANUP_TOKEN_ENV}=$cleanup_token"
+}
+`
+
+const LINUX_TOKEN_SCRIPT = String.raw`${LINUX_IDENTITY_FUNCTIONS}
+key=$1; expected=$2; requested_signal=$3
+matches_token() { test -r "/proc/$1/environ" && tr '\0' '\n' < "/proc/$1/environ" 2>/dev/null | grep -Fqx -- "$key=$expected"; }
+signal_sent=0; passes=1; test -n "$requested_signal" && passes=3
+pass=0
+while test "$pass" -lt "$passes"; do
+  pass=$((pass + 1))
+  for environ in /proc/[0-9]*/environ; do
+    directory=${SHELL_DOLLAR}{environ%/environ}; pid=${SHELL_DOLLAR}{directory##*/}
+    if matches_token "$pid" && read_stat "$pid"; then
+      test -n "$requested_signal" && prefix=CODENOMAD_TARGET || prefix=CODENOMAD_PROCESS
+      emit_linux "$prefix"
+      if test -n "$requested_signal" && matches_token "$pid" && read_stat "$pid" && kill "-$requested_signal" "$pid" 2>/dev/null; then signal_sent=1; fi
+    fi
+  done
+done
+if test -n "$requested_signal"; then printf 'CODENOMAD_RESULT|%s\n' "$signal_sent"; fi
+exit 0
+`
+
+const POSIX_GUARDED_SIGNAL_SCRIPT = String.raw`${POSIX_IDENTITY_FUNCTIONS}
+leader_pid=$1; leader_start=$2; expected_group=$3; requested_signal=$4; allow_leaderless=$5; cleanup_token=$6; shift 6
+matched=0; signal_sent=0
+if read_identity "$leader_pid" && test "$current_group" = "$expected_group" && test "$current_identity" = "$leader_start"; then
+  matched=1
+  for current_pid in $(group_pids "$expected_group"); do
+    read_identity "$current_pid" && test "$current_group" = "$expected_group" && emit_target
+  done
+  if kill "-$requested_signal" -- "-$expected_group" 2>/dev/null; then signal_sent=1; fi
+elif test "$allow_leaderless" = 1 && ! read_identity "$expected_group"; then
+  anchor=0
+  while test "$#" -ge 2; do
+    expected_pid=$1; expected_start=$2; shift 2; current_pid=$expected_pid
+    if read_identity "$expected_pid" && test "$current_group" = "$expected_group" && test "$current_identity" = "$expected_start"; then anchor=1; fi
+  done
+  if test "$anchor" = 0; then
+    for current_pid in $(group_pids "$expected_group"); do
+      if has_cleanup_token "$current_pid" && read_identity "$current_pid" && test "$current_group" = "$expected_group"; then anchor=1; break; fi
+    done
+  fi
+  if test "$anchor" = 1; then
+    matched=1
+    for current_pid in $(group_pids "$expected_group"); do
+      read_identity "$current_pid" && test "$current_group" = "$expected_group" && emit_target
+    done
+    if kill "-$requested_signal" -- "-$expected_group" 2>/dev/null; then signal_sent=1; fi
+  fi
+else
+  while test "$#" -ge 2; do
+    expected_pid=$1; expected_start=$2; shift 2; current_pid=$expected_pid
+    if read_identity "$expected_pid" && test "$current_group" = "$expected_group" && test "$current_identity" = "$expected_start"; then
+      emit_target; if kill "-$requested_signal" "$expected_pid" 2>/dev/null; then signal_sent=1; fi
+    fi
+  done
+fi
+printf 'CODENOMAD_RESULT|%s||%s\n' "$matched" "$signal_sent"
+`
+
+const POSIX_OWNED_GROUP_SIGNAL_SCRIPT = String.raw`${POSIX_IDENTITY_FUNCTIONS}
+root_pid=$1; requested_signal=$2; matched=0; signal_sent=0
+if read_identity "$root_pid" && test "$current_group" = "$root_pid"; then
+  matched=1
+  for current_pid in $(group_pids "$root_pid"); do
+    read_identity "$current_pid" && test "$current_group" = "$root_pid" && emit_target
+  done
+  if kill "-$requested_signal" -- "-$root_pid" 2>/dev/null; then signal_sent=1; fi
+  for current_pid in $(group_pids "$root_pid"); do
+    read_identity "$current_pid" && test "$current_group" = "$root_pid" && emit_target
+  done
+fi
+printf 'CODENOMAD_RESULT|%s||%s\n' "$matched" "$signal_sent"
+`
+
+const commandError = (result: SpawnSyncReturns<string>): string =>
+  result.error?.message || String(result.stderr ?? result.stdout ?? "").trim() || `exit code ${result.status}`
+
+function parseDelimitedSnapshot(output: string, requireBootId = false): Map<number, ProcessIdentity> | null {
+  const processes = new Map<number, ProcessIdentity>()
+  for (const line of output.split(/\r?\n/)) {
+    if (!line) continue
+    const fields = line.split("|")
+    if (fields.length !== 6) return null
+    const [pidText, parentPidText, groupIdText, startTime = "", bootId = "", startOrder = ""] = fields
+    const pid = Number.parseInt(pidText ?? "", 10)
+    const parentPid = Number.parseInt(parentPidText ?? "", 10)
+    const groupId = Number.parseInt(groupIdText ?? "", 10)
+    if (!/^\d+$/.test(pidText ?? "") || !/^\d+$/.test(parentPidText ?? "") || !/^\d+$/.test(groupIdText ?? "") ||
+      !Number.isInteger(pid) || pid <= 0 || !Number.isInteger(parentPid) || !startTime || (requireBootId && !bootId)) return null
+    processes.set(pid, { pid, parentPid, groupId: Number.isInteger(groupId) && groupId > 0 ? groupId : pid, startTime,
+      ...(bootId ? { bootId } : {}), ...(startOrder ? { startOrder } : {}) })
+  }
+  return processes
+}
+
+function decodeBase64Field(value: string): string | null {
+  if (value.length === 0 || value.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    return null
+  }
+  try {
+    const bytes = Buffer.from(value, "base64")
+    if (bytes.toString("base64") !== value) return null
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+  } catch {
+    return null
+  }
+}
+
+function parseBase64Snapshot(output: string, prefix = "CODENOMAD_B64|"): Map<number, ProcessIdentity> | null {
+  const processes = new Map<number, ProcessIdentity>()
+  for (const line of output.split(/\r?\n/)) {
+    if (!line) continue
+    if (!line.startsWith(prefix)) return null
+    const fields = line.slice(prefix.length).split("|")
+    if (fields.length !== 5) return null
+    const [pidText = "", parentPidText = "", groupIdText = "", startEncoded = "", commandEncoded = ""] = fields
+    if (!/^\d+$/.test(pidText) || !/^\d+$/.test(parentPidText) || !/^\d+$/.test(groupIdText)) return null
+    const pid = Number.parseInt(pidText, 10)
+    const parentPid = Number.parseInt(parentPidText, 10)
+    const groupId = Number.parseInt(groupIdText, 10)
+    const start = decodeBase64Field(startEncoded)
+    const command = decodeBase64Field(commandEncoded)
+    if (pid <= 0 || parentPid < 0 || groupId <= 0 || start === null || command === null) return null
+    processes.set(pid, { pid, parentPid, groupId, startTime: `${start}\t${command}` })
+  }
+  return processes
+}
+
+function parsePortablePosixSnapshot(output: string, filter?: PosixProcessFilter): Map<number, ProcessIdentity> | null {
+  const processes = new Map<number, ProcessIdentity>()
+  const requestedPids = filter?.pids ? new Set(filter.pids) : undefined
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.trim()) continue
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+\s+\S+\s+\d+\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s+(.+)$/)
+    if (!match) {
+      const numeric = line.match(/^\s*(\d+)\s+(\d+)\s+(\d+)\s+/)
+      if (!filter || !numeric || requestedPids?.has(Number(numeric[1])) || Number(numeric[3]) === filter.groupId) return null
+      continue
+    }
+    const [, pidText = "", parentPidText = "", groupIdText = "", start = "", command = ""] = match
+    const pid = Number.parseInt(pidText, 10)
+    const parentPid = Number.parseInt(parentPidText, 10)
+    const groupId = Number.parseInt(groupIdText, 10)
+    if (pid <= 0 || parentPid < 0 || groupId <= 0) return null
+    if (filter && !requestedPids?.has(pid) && groupId !== filter.groupId) continue
+    processes.set(pid, { pid, parentPid, groupId, startTime: `${start}\t${command}` })
+  }
+  return processes
+}
+
+function querySnapshot(
+  run: () => SpawnSyncReturns<string>,
+  parse: (output: string) => Map<number, ProcessIdentity> | null,
+  options: { allowEmpty?: boolean; malformedError?: string; redact?: (error: string) => string } = {},
+): ProcessSnapshot {
+  const sanitize = options.redact ?? ((error: string) => error)
+  try {
+    const result = run()
+    if (result.status !== 0) return { ok: false, error: sanitize(commandError(result)) }
+    const processes = parse(String(result.stdout ?? ""))
+    if (processes && (options.allowEmpty || processes.size > 0)) return { ok: true, processes }
+    return { ok: false, error: options.malformedError ?? "process identity query returned no parseable processes" }
+  } catch (error) {
+    return { ok: false, error: sanitize(error instanceof Error ? error.message : String(error)) }
+  }
+}
+
+function parsePrefixedSnapshot(output: string, prefix: string): Map<number, ProcessIdentity> | null {
+  const records: string[] = []
+  for (const line of output.split(/\r?\n/)) {
+    if (!line) continue
+    if (!line.startsWith(prefix)) return null
+    records.push(line.slice(prefix.length))
+  }
+  return parseDelimitedSnapshot(records.join("\n"), true)
+}
+
+function parseGuardedResult(result: SpawnSyncReturns<string>): GuardedSignalResult {
+  const signaled = new Map<number, ProcessIdentity>()
+  const failure = (error: string): GuardedSignalResult => ({ ok: false, error,
+    ...(signaled.size > 0 ? { observed: Array.from(signaled.values()) } : {}) })
+  let matched: boolean | undefined
+  let signalSent = false
+  let cutoff: string | undefined
+  for (const line of String(result.stdout ?? "").split(/\r?\n/)) {
+    if (line.startsWith("CODENOMAD_TARGET|") || line.startsWith("CODENOMAD_TARGET_B64|")) {
+      const parsed = line.startsWith("CODENOMAD_TARGET_B64|")
+        ? parseBase64Snapshot(line, "CODENOMAD_TARGET_B64|")
+        : parseDelimitedSnapshot(line.slice("CODENOMAD_TARGET|".length))
+      if (!parsed) return failure("guarded signal command returned a malformed target record")
+      for (const identity of parsed.values()) signaled.set(identity.pid, identity)
+      continue
+    }
+    if (line.startsWith("CODENOMAD_RESULT|")) {
+      const fields = line.split("|")
+      if (fields.length !== 4 || !/^[01]$/.test(fields[1] ?? "") || !/^[01]$/.test(fields[3] ?? "")) {
+        return failure("guarded signal command returned a malformed result record")
+      }
+      const [, matchedText, cutoffText, signalSentText] = fields
+      matched = matchedText === "1"
+      cutoff = cutoffText || undefined
+      signalSent = signalSentText === "1"
+      continue
+    }
+    if (line) return failure("guarded signal command returned unexpected output")
+  }
+  if (result.status !== 0) return failure(commandError(result))
+  return matched === undefined
+    ? failure("guarded signal command returned no structured result")
+    : { ok: true, matched, signalSent, signaled: Array.from(signaled.values()), ...(cutoff ? { cutoff } : {}) }
+}
+
+function runGuardedCommand(run: () => SpawnSyncReturns<string>): GuardedSignalResult {
+  try {
+    return parseGuardedResult(run())
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+const signalName = (signal: NodeJS.Signals): "TERM" | "KILL" => signal === "SIGKILL" ? "KILL" : "TERM"
+
+function runLinuxScript(spawnCommand: SpawnCommand, script: string, args: string[], timeoutMs: number,
+  label: string, distro?: string): SpawnSyncReturns<string> {
+  return distro
+    ? spawnCommand("wsl.exe", ["--distribution", distro, "--exec", "sh", "-c", script, label, ...args], { encoding: "utf8", timeout: timeoutMs })
+    : spawnCommand("sh", ["-c", script, label, ...args], { encoding: "utf8", timeout: timeoutMs })
+}
+
+const redactToken = (value: string, token: string): string => value.split(token).join("[REDACTED]")
+
+function shellGuardArgs(request: GuardedSignalRequest, linux: boolean): string[] {
+  const leader = request.leader
+  const args = linux
+    ? [String(leader?.pid ?? 0), leader?.startTime ?? "", leader?.bootId ?? "", String(request.groupId ?? 0), signalName(request.signal)]
+    : [String(leader?.pid ?? 0), leader?.startTime ?? "", String(request.groupId ?? 0), signalName(request.signal),
+        request.allowLeaderlessGroup ? "1" : "0", request.cleanupToken ?? ""]
+  for (const member of request.members) {
+    args.push(String(member.pid), member.startTime)
+    if (linux) args.push(member.bootId ?? "")
+  }
+  return args
+}
+
+const quotePowerShell = (value: string): string => `'${value.replace(/'/g, "''")}'`
+
+function buildWindowsGuardedScript(request: GuardedSignalRequest): string {
+  const leaderPid = request.leader?.pid ?? 0
+  const leaderStart = quotePowerShell(request.leader?.startTime ?? "")
+  const expected = request.members.map(
+    (identity) => `@{ Pid = ${identity.pid}; Start = ${quotePowerShell(identity.startTime)} }`,
+  ).join(", ")
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    `$leaderPid = ${leaderPid}`,
+    `$leaderStart = ${leaderStart}`,
+    `$expected = @(${expected})`,
+    "function Get-CodeNomadStart($process) { return ([datetime]$process.CreationDate).ToUniversalTime().Ticks.ToString() }",
+    "$all = @(Get-CimInstance Win32_Process -ErrorAction Stop)",
+    "$byPid = @{}; $all | ForEach-Object { $byPid[[int]$_.ProcessId] = $_ }",
+    "$leader = $byPid[$leaderPid]",
+    "$matched = $null -ne $leader -and (Get-CodeNomadStart $leader) -eq $leaderStart",
+    "$selected = @()",
+    "if ($matched) {",
+    "  $ids = @($leaderPid); $changed = $true",
+    "  while ($changed) { $changed = $false; foreach ($process in $all) { if ($ids -contains [int]$process.ParentProcessId -and $ids -notcontains [int]$process.ProcessId) { $ids += [int]$process.ProcessId; $changed = $true } } }",
+    "  $selected = @($all | Where-Object { $ids -contains [int]$_.ProcessId } | Sort-Object ProcessId -Descending)",
+    "} else {",
+    "  foreach ($item in $expected) { $process = $byPid[[int]$item.Pid]; if ($null -ne $process -and (Get-CodeNomadStart $process) -eq [string]$item.Start) { $selected += $process } }",
+    "}",
+    "foreach ($process in $selected) {",
+    "  $start = Get-CodeNomadStart $process",
+    "  '{0}|{1}|0|{2}||{2}' -f [int]$process.ProcessId, [int]$process.ParentProcessId, $start | ForEach-Object { 'CODENOMAD_TARGET|' + $_ }",
+    "}",
+    "foreach ($process in $selected) {",
+    "  Invoke-CimMethod -InputObject $process -MethodName Terminate -Arguments @{ Reason = 1 } -ErrorAction Stop | Out-Null",
+    "}",
+    "'CODENOMAD_RESULT|' + ($(if ($matched) { '1' } else { '0' })) + '||' + ($(if ($selected.Count -gt 0) { '1' } else { '0' }))",
+  ].join("; ")
+}
+
+export function sameProcess(left: ProcessIdentity | undefined, right: ProcessIdentity | undefined): boolean {
+  return Boolean(left && right && left.pid === right.pid && left.startTime === right.startTime &&
+    (!left.bootId || !right.bootId || left.bootId === right.bootId))
+}
+
+export function startedNoLaterThan(identity: ProcessIdentity, cutoff: string): boolean {
+  const startOrder = identity.startOrder ?? identity.startTime
+  if (!/^\d+$/.test(startOrder) || !/^\d+$/.test(cutoff)) return false
+  try {
+    return BigInt(startOrder) <= BigInt(cutoff)
+  } catch {
+    return false
+  }
+}
+
+export function descendantsOf(processes: Map<number, ProcessIdentity>, rootPid: number): ProcessIdentity[] {
+  const descendants: ProcessIdentity[] = []
+  const pending = [rootPid]
+  const seen = new Set(pending)
+  while (pending.length > 0) {
+    const parentPid = pending.shift()!
+    for (const process of processes.values()) {
+      if (process.parentPid !== parentPid || seen.has(process.pid)) continue
+      seen.add(process.pid)
+      pending.push(process.pid)
+      descendants.push(process)
+    }
+  }
+  return descendants
+}
+
+export function probePosixProcesses(spawnCommand: SpawnCommand, timeoutMs: number,
+  platform: NodeJS.Platform = process.platform, filter?: PosixProcessFilter): ProcessSnapshot {
+  if (platform === "linux") {
+    const pids = filter?.pids?.filter((pid) => Number.isInteger(pid) && pid > 0).map(String) ?? []
+    const launchGroupProbe = pids.length === 1 && filter?.groupId === Number(pids[0])
+    return querySnapshot(
+      () => runLinuxScript(spawnCommand, launchGroupProbe ? LINUX_LAUNCH_GROUP_SNAPSHOT_SCRIPT : LINUX_SNAPSHOT_SCRIPT,
+        launchGroupProbe ? pids : [], timeoutMs, "codenomad-posix-identity"),
+      (output) => parseDelimitedSnapshot(output, true),
+      { allowEmpty: Boolean(filter) },
+    )
+  }
+  // POSIX has no portable pidfd/start ticks; collect one coherent table instead of probing every PID.
+  return querySnapshot(
+    () => spawnCommand("ps", ["-axo", "pid=,ppid=,pgid=,lstart=,comm="], {
+      encoding: "utf8", timeout: timeoutMs, env: { ...process.env, LC_ALL: "C", LANG: "C" },
+    }),
+    (output) => parsePortablePosixSnapshot(output, filter),
+    { allowEmpty: Boolean(filter) },
+  )
+}
+
+export function probeWindowsProcesses(spawnCommand: SpawnCommand, timeoutMs: number): ProcessSnapshot {
+  const script = [
+    "$all = @(Get-CimInstance Win32_Process -ErrorAction Stop)",
+    "$all | Where-Object { [int]$_.ProcessId -gt 0 } | ForEach-Object { $start = ([datetime]$_.CreationDate).ToUniversalTime().Ticks.ToString(); '{0}|{1}|0|{2}||{2}' -f [int]$_.ProcessId, [int]$_.ParentProcessId, $start }",
+  ].join("; ")
+  return querySnapshot(
+    () => spawnCommand("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { encoding: "utf8", timeout: timeoutMs }),
+    parseDelimitedSnapshot,
+  )
+}
+
+export function probeWslProcesses(spawnCommand: SpawnCommand, distro: string, timeoutMs: number): ProcessSnapshot {
+  return querySnapshot(
+    () => runLinuxScript(spawnCommand, LINUX_SNAPSHOT_SCRIPT, [], timeoutMs, "codenomad-wsl-identity", distro),
+    (output) => parseDelimitedSnapshot(output, true),
+  )
+}
+
+export function signalPosixProcesses(spawnCommand: SpawnCommand, request: GuardedSignalRequest,
+  timeoutMs: number, platform: NodeJS.Platform): GuardedSignalResult {
+  const linux = platform === "linux"
+  return runGuardedCommand(() => spawnCommand(
+    "sh",
+    ["-c", linux ? LINUX_GUARDED_SIGNAL_SCRIPT : POSIX_GUARDED_SIGNAL_SCRIPT, "codenomad-guarded-signal", ...shellGuardArgs(request, linux)],
+    { encoding: "utf8", timeout: timeoutMs },
+  ))
+}
+
+export function signalOwnedPosixProcessGroup(spawnCommand: SpawnCommand, rootPid: number,
+  signal: NodeJS.Signals, timeoutMs: number): GuardedSignalResult {
+  return runGuardedCommand(() => spawnCommand(
+    "sh",
+    ["-c", POSIX_OWNED_GROUP_SIGNAL_SCRIPT, "codenomad-owned-group-cleanup", String(rootPid), signalName(signal)],
+    { encoding: "utf8", timeout: timeoutMs },
+  ))
+}
+
+export function signalWslProcesses(spawnCommand: SpawnCommand, distro: string,
+  request: GuardedSignalRequest, timeoutMs: number): GuardedSignalResult {
+  return runGuardedCommand(() => runLinuxScript(
+      spawnCommand,
+      LINUX_GUARDED_SIGNAL_SCRIPT,
+      shellGuardArgs(request, true),
+      timeoutMs,
+      "codenomad-wsl-guarded-signal",
+      distro,
+  ))
+}
+
+export function signalWindowsProcesses(spawnCommand: SpawnCommand, request: GuardedSignalRequest,
+  timeoutMs: number): GuardedSignalResult {
+  return runGuardedCommand(() => spawnCommand(
+    "powershell.exe",
+    ["-NoProfile", "-NonInteractive", "-Command", buildWindowsGuardedScript(request)],
+    { encoding: "utf8", timeout: timeoutMs },
+  ))
+}
+
+export function probeLaunchCleanupToken(spawnCommand: SpawnCommand, token: string,
+  timeoutMs: number, distro?: string): ProcessSnapshot {
+  return querySnapshot(
+    () => runLinuxScript(
+      spawnCommand,
+      LINUX_TOKEN_SCRIPT,
+      [LAUNCH_CLEANUP_TOKEN_ENV, token, ""],
+      timeoutMs,
+      "codenomad-token-cleanup",
+      distro,
+    ),
+    (output) => parsePrefixedSnapshot(output, "CODENOMAD_PROCESS|"),
+    {
+      allowEmpty: true,
+      malformedError: "launch cleanup probe returned malformed or unexpected output",
+      redact: (error) => redactToken(error, token),
+    },
+  )
+}
+
+export function signalLaunchCleanupToken(spawnCommand: SpawnCommand, token: string,
+  signal: NodeJS.Signals, timeoutMs: number, distro?: string): TokenSignalResult {
+  const failed = (error: string): TokenSignalResult => ({ ok: false, signalSent: false, targets: [], error })
+  try {
+    const result = runLinuxScript(
+      spawnCommand,
+      LINUX_TOKEN_SCRIPT,
+      [LAUNCH_CLEANUP_TOKEN_ENV, token, signalName(signal)],
+      timeoutMs,
+      "codenomad-token-cleanup",
+      distro,
+    )
+    if (result.status !== 0) return failed(redactToken(commandError(result), token))
+    const lines = String(result.stdout ?? "").split(/\r?\n/).filter(Boolean)
+    const resultLines = lines.filter((line) => line.startsWith("CODENOMAD_RESULT|"))
+    if (resultLines.length !== 1 || !/^CODENOMAD_RESULT\|[01]$/.test(resultLines[0] ?? "")) {
+      return failed("launch cleanup signal returned no valid structured result")
+    }
+    const targets = parsePrefixedSnapshot(
+      lines.filter((line) => !line.startsWith("CODENOMAD_RESULT|")).join("\n"),
+      "CODENOMAD_TARGET|",
+    )
+    return targets
+      ? { ok: true, signalSent: resultLines[0]!.endsWith("1"), targets: Array.from(targets.values()) }
+      : failed("launch cleanup signal returned malformed or unexpected output")
+  } catch (error) {
+    return failed(redactToken(error instanceof Error ? error.message : String(error), token))
+  }
+}
diff --git a/packages/server/src/workspaces/runtime.test.ts b/packages/server/src/workspaces/runtime.test.ts
new file mode 100644
index 00000000..54fb92a9
--- /dev/null
+++ b/packages/server/src/workspaces/runtime.test.ts
@@ -0,0 +1,265 @@
+import assert from "node:assert/strict"
+import type { ChildProcess, SpawnSyncReturns } from "node:child_process"
+import { EventEmitter } from "node:events"
+import { PassThrough } from "node:stream"
+import { describe, it } from "node:test"
+import pino from "pino"
+
+import { EventBus } from "../events/bus"
+import { WorkspaceRuntime, WorkspaceRuntimeIdentityCaptureError, WorkspaceStopTimeoutError,
+  WorkspaceWindowsTreeCleanupIncompleteError, type WorkspaceRuntimeOptions } from "./runtime"
+type Timer = ReturnType<typeof setTimeout>
+type Command = typeof import("node:child_process").spawnSync
+type Call = { command: string; args: readonly string[] }
+class ManualTimers {
+  private id = 0
+  private pending = new Map<number, { callback: () => void; delay: number }>()
+  set = (callback: () => void, delay: number) => { const id = ++this.id; this.pending.set(id, { callback, delay }); return id as unknown as Timer }
+  clear = (timer: Timer) => this.pending.delete(timer as unknown as number)
+  run(): void {
+    const next = [...this.pending].sort((a, b) => a[1].delay - b[1].delay || a[0] - b[0])[0]
+    assert.ok(next, "expected a pending timer")
+    this.pending.delete(next[0])
+    next[1].callback()
+  }
+}
+class FakeChild extends EventEmitter {
+  stdout = new PassThrough()
+  stderr = new PassThrough()
+  exitCode: number | null = null
+  signalCode: NodeJS.Signals | null = null
+  signals: NodeJS.Signals[] = []
+  constructor(readonly pid: number | undefined = 4242) { super() }
+  kill(signal: NodeJS.Signals = "SIGTERM") { this.signals.push(signal); return true }
+  exit(code: number | null = 0, signal: NodeJS.Signals | null = null) { this.exitCode = code; this.signalCode = signal; this.emit("exit", code, signal) }
+}
+const result = (stdout = "", status = 0, stderr = ""): SpawnSyncReturns<string> =>
+  ({ pid: 1, output: [null, stdout, stderr], stdout, stderr, status, signal: null })
+const posix = (rows: Array<[number, number, number, string]>, boot = "boot-a") =>
+  rows.map(([pid, ppid, pgid, start]) => `${pid}|${ppid}|${pgid}|${start}|${boot}|${start}`).join("\n")
+const portable = (rows: Array<[number, number, number, string, string]>) =>
+  rows.map(([pid, ppid, pgid, start, command]) => `${pid} ${ppid} ${pgid} ${start} ${command}`).join("\n")
+const windows = (rows: Array<[number, number, string]>) =>
+  rows.map(([pid, ppid, start], i) => `${pid}|${ppid}|0|${start}||${100 + i}`).join("\n")
+const guarded = (matched: boolean, rows: Array<[number, number, number, string]>, boot = "boot-a") => [
+  ...rows.map(([pid, ppid, pgid, start]) => `CODENOMAD_TARGET|${pid}|${ppid}|${pgid}|${start}|${boot}|${start}`),
+  `CODENOMAD_RESULT|${matched ? "1" : "0"}|200|${rows.length ? "1" : "0"}`,
+].join("\n")
+const token = (rows: Array<[number, number, number, string]>, signal: boolean, boot = "boot-a") => [
+  ...rows.map(([pid, ppid, pgid, start]) => `${signal ? "CODENOMAD_TARGET" : "CODENOMAD_PROCESS"}|${pid}|${ppid}|${pgid}|${start}|${boot}|${start}`),
+  ...(signal ? [`CODENOMAD_RESULT|${rows.length ? "1" : "0"}`] : []),
+].join("\n")
+const isToken = (args: readonly string[]) => args.includes("codenomad-token-cleanup")
+const isSignal = (args: readonly string[]) => isToken(args) && (args.includes("TERM") || args.includes("KILL"))
+const isGuarded = (args: readonly string[]) => !isToken(args) && args.some((arg) => arg.includes("guarded-signal") || arg.includes("CODENOMAD_RESULT"))
+async function harness(options: WorkspaceRuntimeOptions & { binary?: string; output?: string; report?: boolean } = {}) {
+  const child = new FakeChild()
+  const timers = new ManualTimers()
+  const calls: Call[] = []
+  const platform = options.platform ?? "linux"
+  const command = options.spawnSync ?? ((command: string, args: readonly string[]) => {
+    calls.push({ command, args: [...args] })
+    const alive = child.exitCode === null && child.signalCode === null
+    if (isToken(args)) return result(token(alive ? [[4242, 1, 4242, "100"]] : [], isSignal(args)))
+    if (isGuarded(args)) return result(platform === "win32"
+      ? "CODENOMAD_TARGET|4242|1|0|win-start||100\nCODENOMAD_RESULT|1||1"
+      : guarded(true, [[4242, 1, 4242, "100"]]))
+    return result(platform === "win32"
+      ? windows(alive ? [[4242, 1, "win-start"]] : [])
+      : posix(alive ? [[4242, 1, 4242, "100"]] : [[1, 0, 1, "10"]]))
+  }) as Command
+  const runtime = new WorkspaceRuntime(new EventBus(), pino({ level: "silent" }), {
+    platform, gracefulStopTimeoutMs: 10, forcedStopTimeoutMs: 10, ...options,
+    spawnSync: command, setTimeout: timers.set, clearTimeout: timers.clear,
+    spawn: (() => child as unknown as ChildProcess) as typeof import("node:child_process").spawn,
+  })
+  const abort = new AbortController()
+  const folder = platform === "win32" && process.platform !== "win32" ? `/${process.cwd()}` : process.cwd()
+  const launch = runtime.launch({ workspaceId: "w", folder, binaryPath: options.binary ?? "opencode", signal: abort.signal })
+  if (options.report !== false) {
+    queueMicrotask(() => child.stdout.write(options.output ?? "opencode server listening on http://127.0.0.1:4321\n"))
+    await launch
+  }
+  return { runtime, child, timers, calls, launch, abort }
+}
+describe("workspace runtime lifecycle contracts", () => {
+  it("captures the Linux launch group with one bounded shell command", async () => {
+    let launchCall: Call | undefined
+    await harness({ spawnSync: ((command: string, args: readonly string[]) => {
+      launchCall ??= { command, args: [...args] }
+      return result(posix([[4242, 1, 4242, "100"]]))
+    }) as unknown as Command })
+    assert.deepEqual(launchCall?.args.slice(-1), ["4242"])
+  })
+
+  it("cancels before spawn and while waiting for a port without losing retryable cleanup", async () => {
+    let spawned = false
+    const runtime = new WorkspaceRuntime(new EventBus(), pino({ level: "silent" }), {
+      spawn: (() => { spawned = true; return new FakeChild() as unknown as ChildProcess }) as typeof import("node:child_process").spawn,
+    })
+    const pre = new AbortController(); pre.abort(new Error("pre-cancelled"))
+    await assert.rejects(runtime.launch({ workspaceId: "pre", folder: process.cwd(), binaryPath: "opencode", signal: pre.signal }), /pre-cancelled/)
+    assert.equal(spawned, false)
+
+    let alive = true
+    const h = await harness({ report: false, spawnSync: ((_command: string, args: readonly string[]) => {
+      if (isToken(args)) return result(token(alive ? [[4242, 1, 4242, "100"]] : [], isSignal(args)))
+      if (isGuarded(args)) return result(guarded(true, [[4242, 1, 4242, "100"]]))
+      return result(posix(alive ? [[4242, 1, 4242, "100"]] : [[1, 0, 1, "10"]]))
+    }) as unknown as Command })
+    h.abort.abort(new Error("port-cancelled"))
+    await assert.rejects(h.launch, /port-cancelled/)
+    const first = h.runtime.stop("w"); h.timers.run(); h.timers.run()
+    await assert.rejects(first, WorkspaceStopTimeoutError)
+    alive = false
+    const retry = h.runtime.stop("w"); h.child.exit(); await retry
+
+    const direct = await harness({ report: false })
+    const stopped = direct.runtime.stop("w")
+    await assert.rejects(direct.launch, /runtime launch was cancelled/)
+    direct.child.exit()
+    await stopped
+  })
+  it("rejects launches whose immutable identity cannot be captured and safely cleans up", async () => {
+    for (const scenario of [{ platform: "linux" as const, binary: "opencode" }, { platform: "win32" as const, binary: "opencode.exe" }]) {
+      const child = new FakeChild(scenario.platform === "linux" ? undefined : 4242)
+      const runtime = new WorkspaceRuntime(new EventBus(), pino({ level: "silent" }), {
+        platform: scenario.platform,
+        spawn: (() => child as unknown as ChildProcess) as typeof import("node:child_process").spawn,
+        spawnSync: (() => result("", 1, "identity unavailable")) as unknown as Command,
+      })
+      await assert.rejects(runtime.launch({ workspaceId: scenario.platform, folder: process.cwd(), binaryPath: scenario.binary }), WorkspaceRuntimeIdentityCaptureError)
+      assert.deepEqual(child.signals, ["SIGTERM"])
+      assert.doesNotThrow(() => child.emit("error", new Error("late spawn error")))
+    }
+  })
+  it("signals identity-matched POSIX, Windows, and WSL processes", async () => {
+    const scenarios = [
+      { name: "POSIX", platform: "linux" as const, binary: "opencode", marker: "codenomad-guarded-signal" },
+      { name: "Windows", platform: "win32" as const, binary: "opencode.exe", marker: "CODENOMAD_RESULT" },
+      { name: "WSL", platform: "win32" as const, binary: "\\\\wsl$\\Ubuntu\\usr\\bin\\opencode", marker: "codenomad-wsl-guarded-signal",
+        output: "__CODENOMAD_WSL_PID__:99:99:50:wsl-boot\nopencode server listening on http://127.0.0.1:4321\n" },
+    ]
+    for (const scenario of scenarios) {
+      let alive = true
+      const calls: Call[] = []
+      const h = await harness({ platform: scenario.platform, binary: scenario.binary, output: scenario.output, spawnSync: ((command: string, args: readonly string[]) => {
+        calls.push({ command, args: [...args] })
+        const wsl = scenario.name === "WSL"
+        if (wsl && command === "powershell.exe") return result(windows([[4242, 1, "host-start"]]))
+        if (isToken(args)) { const rows: Array<[number, number, number, string]> = alive ? [[wsl ? 99 : 4242, 1, wsl ? 99 : 4242, wsl ? "50" : "100"]] : []; if (isSignal(args)) alive = false; return result(token(rows, isSignal(args), wsl ? "wsl-boot" : "boot-a")) }
+        if (isGuarded(args)) { alive = false; return result(wsl ? guarded(true, [[99, 1, 99, "50"]], "wsl-boot") : scenario.platform === "win32" ? "CODENOMAD_TARGET|4242|1|0|win-start||100\nCODENOMAD_RESULT|1||1" : guarded(true, [[4242, 1, 4242, "100"]])) }
+        return result(wsl
+          ? posix(alive ? [[99, 1, 99, "50"]] : [[1, 0, 1, "10"]], "wsl-boot")
+          : scenario.platform === "win32"
+            ? windows(alive ? [[4242, 1, "win-start"]] : [[1, 0, "system-start"]])
+            : posix(alive ? [[4242, 1, 4242, "100"]] : [[1, 0, 1, "10"]]))
+      }) as unknown as Command })
+      const stop = h.runtime.stop("w")
+      h.child.exit()
+      await stop
+      assert.ok(calls.some(({ args }) => args.some((arg) => arg.includes(scenario.marker))), `${scenario.name} signal`)
+      assert.equal(calls.some(({ command }) => command === "taskkill.exe"), false)
+    }
+  })
+  it("does not signal a reused PID or process group", async () => {
+    let launched = false
+    const calls: string[][] = []
+    const h = await harness({ spawnSync: ((_command: string, args: readonly string[]) => {
+      calls.push([...args])
+      if (isToken(args)) return result(token([], isSignal(args)))
+      if (isGuarded(args)) return result(guarded(true, [[4242, 1, 4242, "100"]]))
+      if (!launched) { launched = true; return result(posix([[4242, 1, 4242, "100"]])) }
+      return result(posix([[4242, 1, 4242, "300"], [6000, 4242, 4242, "150"]]))
+    }) as unknown as Command })
+    await h.runtime.stop("w")
+    assert.ok(calls.every((args) => !args.includes("6000") && !args.includes("300")))
+  })
+  it("retains and cleans a portable process group after its leader exits", async () => {
+    const start = "Fri Jul 10 12:34:56 2026"
+    let alive = true
+    let leaderExited = false
+    const guardedCalls: readonly string[][] = []
+    const h = await harness({ platform: "darwin", spawnSync: ((_command: string, args: readonly string[]) => {
+      if (isGuarded(args)) {
+        (guardedCalls as string[][]).push([...args])
+        alive = false
+        return result(`CODENOMAD_TARGET_B64|5000|1|4242|${Buffer.from(start).toString("base64")}|${Buffer.from("opencode-child").toString("base64")}\nCODENOMAD_RESULT|1||1`)
+      }
+      const rows: Array<[number, number, number, string, string]> = !alive
+        ? []
+        : leaderExited
+          ? [[5000, 4242, 4242, start, "opencode-child"]]
+          : [[4242, 1, 4242, start, "opencode"]]
+      return result(portable(rows))
+    }) as unknown as Command })
+
+    leaderExited = true
+    h.child.exit(1)
+    await new Promise<void>((resolve) => setImmediate(resolve))
+    assert.equal(guardedCalls.length, 1)
+    assert.equal(guardedCalls[0]?.[7], "1")
+    assert.equal((h.runtime as unknown as { processes: Map<string, unknown> }).processes.size, 0)
+  })
+  it("refuses a leaderless portable group when no retained identity anchor remains", async () => {
+    const start = "Fri Jul 10 12:34:56 2026"
+    let leaderExited = false
+    const guardedCalls: readonly string[][] = []
+    const h = await harness({ platform: "darwin", spawnSync: ((_command: string, args: readonly string[]) => {
+      if (isGuarded(args)) {
+        (guardedCalls as string[][]).push([...args])
+        return result("CODENOMAD_RESULT|0||0")
+      }
+      return result(portable(leaderExited
+        ? [[6000, 1, 4242, "Fri Jul 10 99:99:99 2026", "unverified-process"]]
+        : [[4242, 1, 4242, start, "opencode"]]))
+    }) as unknown as Command })
+
+    leaderExited = true
+    h.child.exit(1)
+    const cleanup = h.runtime.stop("w")
+    h.timers.run(); h.timers.run()
+    await assert.rejects(cleanup, (error: unknown) =>
+      error instanceof WorkspaceStopTimeoutError && /no longer has a verified identity anchor/.test(error.message))
+    assert.equal(guardedCalls.length, 2)
+    assert.ok(guardedCalls.every((args) => args[7] === "1" && !args.includes("6000")))
+    assert.equal((h.runtime as unknown as { processes: Map<string, unknown> }).processes.size, 1)
+  })
+  it("bounds direct Windows cleanup without falling back to taskkill", async () => {
+    const calls: Call[] = []
+    const h = await harness({ platform: "win32", binary: "opencode.exe", spawnSync: ((command: string, args: readonly string[]) => {
+      calls.push({ command, args: [...args] })
+      return isGuarded(args) ? result("CODENOMAD_TARGET|4242|1|0|win-start||100\nCODENOMAD_RESULT|1||1") : result(windows([[4242, 1, "win-start"]]))
+    }) as unknown as Command })
+    const stop = h.runtime.stop("w"); h.timers.run(); h.timers.run()
+    await assert.rejects(stop, WorkspaceStopTimeoutError)
+    assert.equal(calls.some(({ command }) => command === "taskkill.exe"), false)
+    assert.equal(calls.filter(({ args }) => isGuarded(args)).length, 2)
+  })
+  it("escalates wrapper cleanup, reports incomplete exited trees, and permits retry", async () => {
+    let available = false
+    const calls: Call[] = []
+    const h = await harness({ platform: "win32", binary: "opencode.cmd", spawnSync: ((command: string, args: readonly string[]) => {
+      calls.push({ command, args: [...args] })
+      return available ? result() : result("", 1, "taskkill unavailable")
+    }) as unknown as Command })
+    const first = h.runtime.stop("w"); h.timers.run(); h.timers.run()
+    await assert.rejects(first, (error: unknown) => error instanceof WorkspaceStopTimeoutError && /\/T \/F failed/.test(error.message))
+    assert.deepEqual(calls.map(({ args }) => args), [["/PID", "4242", "/T"], ["/PID", "4242", "/T", "/F"]])
+    available = true
+    const retry = h.runtime.stop("w"); h.child.exit(); await retry
+
+    const exited = await harness({ platform: "win32", binary: "opencode.cmd", spawnSync: (() => result("", 1, "taskkill unavailable")) as unknown as Command })
+    const incomplete = exited.runtime.stop("w"); exited.child.exit(1)
+    await assert.rejects(incomplete, WorkspaceWindowsTreeCleanupIncompleteError)
+    await assert.rejects(exited.runtime.stop("w"), WorkspaceWindowsTreeCleanupIncompleteError)
+  })
+  it("shares one bounded stop operation across concurrent callers", async () => {
+    const h = await harness()
+    const first = h.runtime.stop("w"); const second = h.runtime.stop("w")
+    assert.strictEqual(first, second)
+    h.timers.run(); h.timers.run()
+    const outcomes = await Promise.allSettled([first, second])
+    assert.deepEqual(outcomes.map(({ status }) => status), ["rejected", "rejected"])
+  })
+})
diff --git a/packages/server/src/workspaces/runtime.ts b/packages/server/src/workspaces/runtime.ts
index efc77f9a..41adab8c 100644
--- a/packages/server/src/workspaces/runtime.ts
+++ b/packages/server/src/workspaces/runtime.ts
@@ -1,10 +1,29 @@
 import { ChildProcess, spawn, spawnSync } from "child_process"
+import { randomBytes } from "crypto"
 import { existsSync, statSync } from "fs"
 import path from "path"
 import { EventBus } from "../events/bus"
 import { LogLevel, WorkspaceLogEntry } from "../api-types"
 import { Logger } from "../logger"
-import { buildSpawnSpec, buildWslSignalSpec } from "./spawn"
+import { buildSpawnSpec, type SpawnProcessKind } from "./spawn"
+import {
+  descendantsOf,
+  LAUNCH_CLEANUP_TOKEN_ENV,
+  probeLaunchCleanupToken,
+  probePosixProcesses,
+  probeWindowsProcesses,
+  probeWslProcesses,
+  sameProcess,
+  signalPosixProcesses,
+  signalOwnedPosixProcessGroup,
+  signalLaunchCleanupToken,
+  signalWindowsProcesses,
+  signalWslProcesses,
+  startedNoLaterThan,
+  type GuardedSignalResult,
+  type ProcessIdentity,
+  type ProcessSnapshot,
+} from "./process-identity"
 
 const SENSITIVE_ENV_KEY = /(PASSWORD|TOKEN|SECRET)/i
 const WSL_PID_MARKER = "__CODENOMAD_WSL_PID__:"
@@ -28,6 +47,7 @@ interface LaunchOptions {
   environment?: Record<string, string>
   logLevel?: string
   onExit?: (info: ProcessExitInfo) => void
+  signal?: AbortSignal
 }
 
 export interface ProcessExitInfo {
@@ -37,32 +57,131 @@ export interface ProcessExitInfo {
   requested: boolean
 }
 
+interface TrackedProcesses {
+  leader?: ProcessIdentity
+  groupId?: number
+  dispatchCutoff?: string
+  groupOwnershipRetained?: boolean
+  groupGoneConfirmed?: boolean
+  groupOwnershipUncertain?: boolean
+  members: Map<number, ProcessIdentity>
+}
+
 interface ManagedProcess {
   child: ChildProcess
+  cleanupToken: string
+  processKind: SpawnProcessKind
+  windowsTreeCleanupConfirmed?: boolean
+  windowsTreeCleanupFailures?: string[]
+  identityCaptureFailed?: boolean
   requestedStop: boolean
-  wsl?: {
+  stopPromise?: Promise<void>
+  cancelLaunch?: () => void
+  finalizeExit?: (code: number | null, signal: NodeJS.Signals | null) => void
+  targets?: TrackedProcesses
+  wsl?: TrackedProcesses & {
     distro: string
     linuxPid: number | null
+    linuxPgid: number | null
+    leaderStartTime: string | null
+    bootId: string | null
+  }
+}
+
+type RuntimeTimeout = ReturnType<typeof setTimeout>
+
+export interface WorkspaceRuntimeOptions {
+  gracefulStopTimeoutMs?: number
+  forcedStopTimeoutMs?: number
+  stopCommandTimeoutMs?: number
+  platform?: NodeJS.Platform
+  spawn?: typeof spawn
+  spawnSync?: typeof spawnSync
+  setTimeout?: (callback: () => void, delayMs: number) => RuntimeTimeout
+  clearTimeout?: (timer: RuntimeTimeout) => void
+}
+
+export class WorkspaceStopTimeoutError extends Error {
+  readonly code = "WORKSPACE_STOP_TIMEOUT"
+  readonly retryable = true
+
+  constructor(workspaceId: string, pid: number | undefined, timeoutMs: number, liveness: string, failures: string[]) {
+    const failureDetails = failures.length > 0 ? ` Stop failures: ${failures.join("; ")}.` : ""
+    super(
+      `Workspace ${workspaceId} process ${pid ?? "with unknown PID"} did not stop within ${timeoutMs}ms; ${liveness}.` +
+        `${failureDetails} The stop can be retried.`,
+    )
+    this.name = "WorkspaceStopTimeoutError"
+  }
+}
+
+export class WorkspaceWindowsTreeCleanupIncompleteError extends Error {
+  readonly code = "WORKSPACE_WINDOWS_TREE_CLEANUP_INCOMPLETE"
+  readonly retryable = true
+
+  constructor(workspaceId: string, pid: number | undefined, failures: string[]) {
+    const failureDetails = failures.length > 0 ? ` Stop failures: ${failures.join("; ")}.` : ""
+    super(
+      `Workspace ${workspaceId} Windows wrapper ${pid ?? "with unknown PID"} exited before taskkill confirmed process-tree cleanup.` +
+        `${failureDetails} The workspace record was retained because cleanup is incomplete.`,
+    )
+    this.name = "WorkspaceWindowsTreeCleanupIncompleteError"
+  }
+}
+
+export class WorkspaceRuntimeIdentityCaptureError extends Error {
+  readonly code = "WORKSPACE_RUNTIME_IDENTITY_CAPTURE_FAILED"
+
+  constructor(workspaceId: string, detail: string) {
+    super(`Workspace ${workspaceId} process identity capture failed: ${detail}`)
+    this.name = "WorkspaceRuntimeIdentityCaptureError"
   }
 }
 
 export class WorkspaceRuntime {
   private processes = new Map<string, ManagedProcess>()
+  private readonly platform: NodeJS.Platform
+  private readonly spawnProcess: typeof spawn
+  private readonly spawnCommand: typeof spawnSync
+  private readonly scheduleTimeout: (callback: () => void, delayMs: number) => RuntimeTimeout
+  private readonly cancelTimeout: (timer: RuntimeTimeout) => void
+  private readonly gracefulStopTimeoutMs: number
+  private readonly forcedStopTimeoutMs: number
+  private readonly stopCommandTimeoutMs: number
 
-  constructor(private readonly eventBus: EventBus, private readonly logger: Logger) {}
+  constructor(
+    private readonly eventBus: EventBus,
+    private readonly logger: Logger,
+    options: WorkspaceRuntimeOptions = {},
+  ) {
+    this.platform = options.platform ?? process.platform
+    this.spawnProcess = options.spawn ?? spawn
+    this.spawnCommand = options.spawnSync ?? spawnSync
+    this.scheduleTimeout = options.setTimeout ?? setTimeout
+    this.cancelTimeout = options.clearTimeout ?? clearTimeout
+    this.gracefulStopTimeoutMs = Math.max(0, options.gracefulStopTimeoutMs ?? 2000)
+    this.forcedStopTimeoutMs = Math.max(0, options.forcedStopTimeoutMs ?? 2000)
+    this.stopCommandTimeoutMs = Math.max(1, options.stopCommandTimeoutMs ?? 1000)
+  }
 
-  async launch(options: LaunchOptions): Promise<{ pid: number; port: number; exitPromise: Promise<ProcessExitInfo>; getLastOutput: () => string }> {
+  async launch(options: LaunchOptions): Promise<{
+    pid: number
+    port: number
+    exitPromise: Promise<ProcessExitInfo>
+    getLastOutput: () => string
+  }> {
+    options.signal?.throwIfAborted()
     this.validateFolder(options.folder)
 
     const logLevel = typeof options.logLevel === "string" ? options.logLevel.toUpperCase() : "DEBUG"
     const args = ["serve", "--port", "0", "--print-logs", "--log-level", logLevel]
-    const env = { ...process.env, ...(options.environment ?? {}) }
+    const cleanupToken = randomBytes(32).toString("hex")
+    const env = { ...process.env, ...(options.environment ?? {}), [LAUNCH_CLEANUP_TOKEN_ENV]: cleanupToken }
 
     let exitResolve: ((info: ProcessExitInfo) => void) | null = null
     const exitPromise = new Promise<ProcessExitInfo>((resolveExit) => {
       exitResolve = resolveExit
     })
-
     // Store recent output for debugging - keep last 50 lines from each stream
     const MAX_OUTPUT_LINES = 50
     const recentStdout: string[] = []
@@ -81,12 +200,13 @@ export class WorkspaceRuntime {
     }
 
     return new Promise((resolve, reject) => {
-      const propagatedEnvKeys = Object.keys(options.environment ?? {})
+      const propagatedEnvKeys = [...Object.keys(options.environment ?? {}), LAUNCH_CLEANUP_TOKEN_ENV]
       const spec = buildSpawnSpec(options.binaryPath, args, {
         cwd: options.folder,
         env,
         propagateEnvKeys: propagatedEnvKeys,
         wslPidMarker: WSL_PID_MARKER,
+        platform: this.platform,
       })
       const commandLine = [spec.command, ...spec.args].join(" ")
       this.logger.info(
@@ -115,25 +235,80 @@ export class WorkspaceRuntime {
         },
         "OpenCode spawn environment",
       )
-      const detached = process.platform !== "win32"
-      const child = spawn(spec.command, spec.args, {
+      const detached = this.platform !== "win32"
+      const child = this.spawnProcess(spec.command, spec.args, {
         cwd: spec.cwd,
         env: spec.env,
         stdio: ["ignore", "pipe", "pipe"],
         detached,
         ...spec.options,
       })
+      const handleEarlyError = (error: Error) => {
+        this.logger.error({ workspaceId: options.workspaceId, err: error }, "Workspace runtime failed before launch handlers were ready")
+      }
+      child.on("error", handleEarlyError)
 
       const managed: ManagedProcess = {
         child,
+        cleanupToken,
+        processKind: spec.processKind,
         requestedStop: false,
-        ...(spec.wsl ? { wsl: { distro: spec.wsl.distro, linuxPid: null } } : {}),
+        targets: { members: new Map<number, ProcessIdentity>() },
+        ...(spec.wsl
+          ? {
+              wsl: {
+                distro: spec.wsl.distro,
+                linuxPid: null,
+                linuxPgid: null,
+                leaderStartTime: null,
+                bootId: null,
+                members: new Map<number, ProcessIdentity>(),
+              },
+            }
+          : {}),
       }
       this.processes.set(options.workspaceId, managed)
+      if (spec.processKind === "posix" || spec.processKind === "wsl" || spec.processKind === "windows-direct") {
+        const launchSnapshot = child.pid
+          ? this.platform === "win32"
+            ? probeWindowsProcesses(this.spawnCommand, this.stopCommandTimeoutMs)
+            : probePosixProcesses(
+                this.spawnCommand,
+                this.stopCommandTimeoutMs,
+                this.platform,
+                { pids: [child.pid], groupId: child.pid },
+              )
+          : { ok: false as const, error: "spawned child did not expose a PID" }
+        const launchLeader = launchSnapshot.ok && child.pid ? launchSnapshot.processes.get(child.pid) : undefined
+        if (!launchLeader) {
+          const detail = launchSnapshot.ok
+            ? `spawned PID ${child.pid ?? "unknown"} was absent from the identity snapshot`
+            : launchSnapshot.error
+          this.beginFailedLaunchCleanup(options.workspaceId, managed)
+          reject(new WorkspaceRuntimeIdentityCaptureError(options.workspaceId, detail))
+          return
+        }
+        managed.targets!.leader = launchLeader
+        managed.targets!.groupId = launchLeader.groupId
+        managed.targets!.groupOwnershipRetained = this.platform !== "linux" && this.platform !== "win32" &&
+          launchLeader.groupId === launchLeader.pid
+        for (const identity of launchSnapshot.ok ? launchSnapshot.processes.values() : [launchLeader]) {
+          if (identity.groupId === launchLeader.groupId) managed.targets!.members.set(identity.pid, identity)
+        }
+      }
 
       let stdoutBuffer = ""
       let stderrBuffer = ""
       let portFound = false
+      let pendingPort: number | null = null
+      let launchSettled = false
+      const cancelLaunch = () => {
+        if (launchSettled) return
+        launchSettled = true
+        stopWarningTimer()
+        reject(options.signal?.reason ?? new Error(`Workspace ${options.workspaceId} runtime launch was cancelled`))
+      }
+      managed.cancelLaunch = cancelLaunch
 
       let warningTimer: NodeJS.Timeout | null = null
 
@@ -152,16 +327,24 @@ export class WorkspaceRuntime {
 
       startWarningTimer()
 
+      options.signal?.addEventListener("abort", cancelLaunch, { once: true })
+      if (options.signal?.aborted) cancelLaunch()
+
       const cleanupStreams = () => {
         stopWarningTimer()
         child.stdout?.removeAllListeners()
         child.stderr?.removeAllListeners()
       }
 
+      let finalized = false
       const handleExit = (code: number | null, signal: NodeJS.Signals | null) => {
+        if (finalized) return
+        finalized = true
+        const cleanupRequired = !managed.requestedStop
         this.logger.info({ workspaceId: options.workspaceId, code, signal }, "OpenCode process exited")
-        this.processes.delete(options.workspaceId)
         cleanupStreams()
+        options.signal?.removeEventListener("abort", cancelLaunch)
+        managed.cancelLaunch = undefined
         child.removeListener("error", handleError)
         child.removeListener("exit", handleExit)
         const exitInfo: ProcessExitInfo = {
@@ -177,27 +360,71 @@ export class WorkspaceRuntime {
         if (!portFound) {
           const recentOutput = getLastOutput().trim()
           const reason = recentOutput || stderrBuffer || `Process exited with code ${code}`
-          reject(new Error(reason))
+          if (!launchSettled) {
+            launchSettled = true
+            reject(new Error(reason))
+          }
         } else {
           options.onExit?.(exitInfo)
         }
+        if (cleanupRequired && this.processes.get(options.workspaceId) === managed) {
+          void this.stop(options.workspaceId).catch((error) => {
+            this.logger.warn({ workspaceId: options.workspaceId, err: error }, "Unexpected workspace exit cleanup remains pending")
+          })
+        }
       }
+      managed.finalizeExit = handleExit
 
       const handleError = (error: Error) => {
+        const cleanupRequired = !managed.requestedStop
         cleanupStreams()
+        options.signal?.removeEventListener("abort", cancelLaunch)
+        managed.cancelLaunch = undefined
         child.removeListener("exit", handleExit)
-        this.processes.delete(options.workspaceId)
         this.logger.error({ workspaceId: options.workspaceId, err: error }, "Workspace runtime error")
         if (exitResolve) {
           exitResolve({ workspaceId: options.workspaceId, code: null, signal: null, requested: managed.requestedStop })
           exitResolve = null
         }
-        reject(error)
+        if (!launchSettled) {
+          launchSettled = true
+          reject(error)
+        }
+        if (cleanupRequired && this.processes.get(options.workspaceId) === managed) {
+          void this.stop(options.workspaceId).catch((stopError) => {
+            this.logger.warn({ workspaceId: options.workspaceId, err: stopError }, "Workspace error cleanup remains pending")
+          })
+        }
       }
 
+      child.removeListener("error", handleEarlyError)
       child.on("error", handleError)
       child.on("exit", handleExit)
 
+      const resolveLaunchIfIdentified = () => {
+        if (launchSettled || pendingPort === null) return
+        if (managed.wsl && (!managed.wsl.linuxPid || !managed.wsl.linuxPgid || !managed.wsl.leaderStartTime || !managed.wsl.bootId)) {
+          return
+        }
+        portFound = true
+        launchSettled = true
+        stopWarningTimer()
+        options.signal?.removeEventListener("abort", cancelLaunch)
+        managed.cancelLaunch = undefined
+        child.removeListener("error", handleError)
+        this.logger.info({ workspaceId: options.workspaceId, port: pendingPort }, "Workspace runtime allocated port")
+        resolve({ pid: child.pid!, port: pendingPort, exitPromise, getLastOutput })
+      }
+
+      const failWslIdentityCapture = (detail: string) => {
+        if (launchSettled) return
+        launchSettled = true
+        managed.requestedStop = true
+        cleanupStreams()
+        this.beginFailedLaunchCleanup(options.workspaceId, managed)
+        reject(new WorkspaceRuntimeIdentityCaptureError(options.workspaceId, detail))
+      }
+
       child.stdout?.on("data", (data: Buffer) => {
         const text = data.toString()
         stdoutBuffer += text
@@ -209,10 +436,34 @@ export class WorkspaceRuntime {
           if (!trimmed) continue
 
           if (managed.wsl && trimmed.startsWith(WSL_PID_MARKER)) {
-            const linuxPid = Number.parseInt(trimmed.slice(WSL_PID_MARKER.length), 10)
-            if (Number.isFinite(linuxPid) && linuxPid > 0) {
+            const [linuxPidText, linuxPgidText, linuxStartTime = "", bootId = ""] = trimmed.slice(WSL_PID_MARKER.length).split(":", 4)
+            const linuxPid = Number.parseInt(linuxPidText ?? "", 10)
+            const linuxPgid = Number.parseInt(linuxPgidText ?? "", 10)
+            if (Number.isInteger(linuxPid) && linuxPid > 0 && Number.isInteger(linuxPgid) && linuxPgid > 0 && /^\d+$/.test(linuxStartTime) && bootId) {
               managed.wsl.linuxPid = linuxPid
-              this.logger.debug({ workspaceId: options.workspaceId, linuxPid }, "Captured WSL OpenCode PID")
+              managed.wsl.linuxPgid = linuxPgid
+              managed.wsl.leaderStartTime = linuxStartTime
+              managed.wsl.bootId = bootId
+              managed.wsl.members.set(linuxPid, {
+                pid: linuxPid,
+                parentPid: 0,
+                groupId: linuxPgid,
+                startTime: linuxStartTime,
+                bootId,
+                startOrder: linuxStartTime,
+              })
+              this.logger.debug(
+                {
+                  workspaceId: options.workspaceId,
+                  linuxPid,
+                  linuxPgid: managed.wsl.linuxPgid,
+                  linuxStartTime: managed.wsl.leaderStartTime,
+                },
+                "Captured WSL OpenCode process identity",
+              )
+              resolveLaunchIfIdentified()
+            } else {
+              failWslIdentityCapture("WSL launcher returned an incomplete Linux PID identity")
             }
             continue
           }
@@ -226,13 +477,13 @@ export class WorkspaceRuntime {
 
           if (!portFound) {
             const portMatch = line.match(/opencode server listening on http:\/\/.+:(\d+)/i)
-            if (portMatch) {
-              portFound = true
-              stopWarningTimer()
-              child.removeListener("error", handleError)
-              const port = parseInt(portMatch[1], 10)
-              this.logger.info({ workspaceId: options.workspaceId, port }, "Workspace runtime allocated port")
-              resolve({ pid: child.pid!, port, exitPromise, getLastOutput })
+            if (portMatch && !launchSettled) {
+              pendingPort = parseInt(portMatch[1], 10)
+              if (managed.wsl && (!managed.wsl.leaderStartTime || !managed.wsl.bootId)) {
+                failWslIdentityCapture("WSL process reported a port before its Linux identity")
+              } else {
+                resolveLaunchIfIdentified()
+              }
             }
           }
         }
@@ -259,173 +510,323 @@ export class WorkspaceRuntime {
     })
   }
 
-  async stop(workspaceId: string): Promise<void> {
+  private beginFailedLaunchCleanup(workspaceId: string, managed: ManagedProcess): void {
+    managed.identityCaptureFailed = true
+    void this.stop(workspaceId).catch((error) => {
+      this.logger.warn({ workspaceId, err: error }, "Unpublished workspace cleanup remains pending")
+    })
+    if (managed.child.exitCode === null && managed.child.signalCode === null) {
+      try {
+        managed.child.kill("SIGTERM")
+      } catch (error) {
+        this.logger.debug({ workspaceId, err: error }, "Failed initial live-child cleanup signal")
+      }
+    }
+  }
+
+  stop(workspaceId: string): Promise<void> {
     const managed = this.processes.get(workspaceId)
-    if (!managed) return
+    if (!managed) return Promise.resolve()
 
+    if (managed.stopPromise) {
+      return managed.stopPromise
+    }
+
+    const stopPromise = this.stopManagedProcess(workspaceId, managed)
+    managed.stopPromise = stopPromise
+    void stopPromise.finally(() => {
+      if (managed.stopPromise === stopPromise) managed.stopPromise = undefined
+    }).catch(() => undefined)
+    return stopPromise
+  }
+
+  private stopManagedProcess(workspaceId: string, managed: ManagedProcess): Promise<void> {
     managed.requestedStop = true
-    const child = managed.child
+    managed.cancelLaunch?.()
+    managed.cancelLaunch = undefined
     this.logger.info({ workspaceId }, "Stopping OpenCode process")
+    if (managed.processKind === "windows-wrapper") return this.stopOwnedWindowsProcess(workspaceId, managed)
 
+    const { child } = managed
     const pid = child.pid
-    if (!pid) {
-      this.logger.warn({ workspaceId }, "Workspace process missing PID; cannot stop")
-      return
-    }
-
-    const isAlreadyExited = () => child.exitCode !== null || child.signalCode !== null
-
-    const tryKillPosixGroup = (signal: NodeJS.Signals) => {
-      try {
-        // Negative PID targets the process group (POSIX).
-        process.kill(-pid, signal)
-        return true
-      } catch (error) {
-        const err = error as NodeJS.ErrnoException
-        if (err?.code === "ESRCH") {
-          return true
-        }
-        this.logger.debug({ workspaceId, pid, err }, "Failed to signal POSIX process group")
-        return false
+    const failures: string[] = []
+    const wrapperExited = () => child.exitCode !== null || child.signalCode !== null
+    const hasWslIdentity = () => Boolean(
+      managed.wsl?.linuxPid && managed.wsl.linuxPgid && managed.wsl.leaderStartTime && managed.wsl.bootId,
+    )
+    const trackedTarget = () => managed.wsl && hasWslIdentity() ? managed.wsl : managed.targets!
+    const trackedLeader = (): ProcessIdentity | undefined => {
+      if (!managed.wsl || !hasWslIdentity()) return managed.targets?.leader
+      return {
+        pid: managed.wsl.linuxPid!,
+        parentPid: 0,
+        groupId: managed.wsl.linuxPgid!,
+        startTime: managed.wsl.leaderStartTime!,
+        bootId: managed.wsl.bootId!,
+        startOrder: managed.wsl.leaderStartTime!,
       }
     }
 
-    const tryKillSinglePid = (signal: NodeJS.Signals) => {
-      try {
-        process.kill(pid, signal)
-        return true
-      } catch (error) {
-        const err = error as NodeJS.ErrnoException
-        if (err?.code === "ESRCH") {
-          return true
-        }
-        this.logger.debug({ workspaceId, pid, err }, "Failed to signal workspace PID")
-        return false
-      }
-    }
-
-    const tryTaskkill = (force: boolean) => {
-      const args = ["/PID", String(pid), "/T"]
-      if (force) {
-        args.push("/F")
+    const refreshTargets = () => {
+      const target = trackedTarget()
+      const leader = trackedLeader()
+      const groupId = managed.wsl && hasWslIdentity() ? managed.wsl.linuxPgid! : target.groupId
+      const portableGroupId = this.platform !== "linux" && this.platform !== "win32" &&
+        target.groupOwnershipRetained && !target.groupGoneConfirmed ? groupId : undefined
+      const snapshot = managed.wsl && hasWslIdentity()
+        ? probeWslProcesses(this.spawnCommand, managed.wsl.distro, this.stopCommandTimeoutMs)
+        : this.platform === "win32"
+          ? probeWindowsProcesses(this.spawnCommand, this.stopCommandTimeoutMs)
+          : probePosixProcesses(this.spawnCommand, this.stopCommandTimeoutMs, this.platform, this.platform === "linux"
+              ? undefined
+              : { pids: [leader?.pid, ...target.members.keys()].filter((value): value is number => Boolean(value)), groupId: portableGroupId })
+      if (!snapshot.ok) {
+        const platformName = managed.wsl && hasWslIdentity() ? "WSL" : this.platform === "win32" ? "Windows" : "POSIX"
+        failures.push(`${platformName} identity discovery failed: ${snapshot.error}`)
+        return { snapshot, aliveMembers: [] as ProcessIdentity[] }
       }
 
-      try {
-        const result = spawnSync("taskkill", args, { encoding: "utf8" })
-        const exitCode = result.status
-        if (exitCode === 0) {
-          return true
-        }
-        // If the PID is already gone, treat it as success.
-        const stderr = (result.stderr ?? "").toString().toLowerCase()
-        const stdout = (result.stdout ?? "").toString().toLowerCase()
-        const combined = `${stdout}\n${stderr}`
-        if (combined.includes("not found") || combined.includes("no running instance") || combined.includes("process") && combined.includes("not")) {
-          return true
-        }
-        this.logger.debug({ workspaceId, pid, exitCode, stderr: result.stderr, stdout: result.stdout }, "taskkill failed")
-        return false
-      } catch (error) {
-        this.logger.debug({ workspaceId, pid, err: error }, "taskkill failed to execute")
-        return false
+      const leaderMatches = sameProcess(leader, leader ? snapshot.processes.get(leader.pid) : undefined)
+      const groupLeader = groupId ? snapshot.processes.get(groupId) : undefined
+      const groupWasReused = Boolean(groupLeader && !sameProcess(leader, groupLeader))
+      const retainedAnchorMatches = Boolean(portableGroupId && Array.from(target.members.values()).some((identity) =>
+        sameProcess(identity, snapshot.processes.get(identity.pid)),
+      ))
+      if (portableGroupId && groupWasReused) {
+        target.groupGoneConfirmed = true
+        target.groupOwnershipUncertain = false
       }
-    }
-
-    const trySignalWslProcess = (signal: NodeJS.Signals) => {
-      if (process.platform !== "win32" || !managed.wsl?.linuxPid) {
-        return false
-      }
-
-      try {
-        const spec = buildWslSignalSpec(managed.wsl.distro, managed.wsl.linuxPid, signal)
-        const result = spawnSync(spec.command, spec.args, { encoding: "utf8" })
-        const exitCode = result.status
-        if (exitCode === 0) {
-          return true
-        }
-
-        const stderr = (result.stderr ?? "").toString().toLowerCase()
-        const stdout = (result.stdout ?? "").toString().toLowerCase()
-        const combined = `${stdout}\n${stderr}`
-        if (combined.includes("no such process") || combined.includes("not found")) {
-          return true
-        }
-
-        this.logger.debug(
-          { workspaceId, pid, linuxPid: managed.wsl.linuxPid, distro: managed.wsl.distro, exitCode, stderr: result.stderr, stdout: result.stdout },
-          "WSL kill failed",
+      for (const process of snapshot.processes.values()) {
+        const sameBoot = !leader?.bootId || process.bootId === leader.bootId
+        const withinDispatch = (this.platform === "linux" || Boolean(managed.wsl)) && Boolean(
+          target.dispatchCutoff && sameBoot && startedNoLaterThan(process, target.dispatchCutoff),
         )
-        return false
-      } catch (error) {
-        this.logger.debug({ workspaceId, pid, linuxPid: managed.wsl.linuxPid, distro: managed.wsl.distro, err: error }, "WSL kill failed to execute")
-        return false
+        const withinRetainedPortableGroup = Boolean(portableGroupId && !groupWasReused && retainedAnchorMatches)
+        if (groupId && process.groupId === groupId && (leaderMatches || withinRetainedPortableGroup || (!groupWasReused && withinDispatch))) {
+          target.members.set(process.pid, process)
+        }
+      }
+      if (portableGroupId && !groupWasReused) {
+        const groupPresent = Array.from(snapshot.processes.values()).some((process) => process.groupId === portableGroupId)
+        if (!groupPresent) {
+          target.groupGoneConfirmed = true
+          target.groupOwnershipUncertain = false
+        } else if (!leaderMatches && !retainedAnchorMatches) {
+          target.groupOwnershipUncertain = true
+        }
+      }
+      if (this.platform === "win32" && !managed.wsl && leaderMatches && leader) {
+        for (const descendant of descendantsOf(snapshot.processes, leader.pid)) target.members.set(descendant.pid, descendant)
+      }
+      const aliveMembers = Array.from(target.members.values()).filter((identity) =>
+        sameProcess(identity, snapshot.processes.get(identity.pid)),
+      )
+      return { snapshot, aliveMembers }
+    }
+
+    const usesTokenCleanup = () => this.platform === "linux" || Boolean(managed.wsl)
+    const refreshTokenTargets = (): ProcessSnapshot | undefined => {
+      if (!usesTokenCleanup()) return
+      const snapshot = probeLaunchCleanupToken(
+        this.spawnCommand, managed.cleanupToken, this.stopCommandTimeoutMs, managed.wsl?.distro,
+      )
+      if (!snapshot.ok) failures.push(`${managed.wsl ? "WSL" : "Linux"} launch-token discovery failed: ${snapshot.error}`)
+      else for (const identity of snapshot.processes.values()) trackedTarget().members.set(identity.pid, identity)
+      return snapshot
+    }
+    const recordSignalResult = (result: GuardedSignalResult, target: TrackedProcesses, name: string, signal: NodeJS.Signals) => {
+      const identities = result.ok ? result.signaled : (result.observed ?? [])
+      for (const identity of identities) target.members.set(identity.pid, identity)
+      if (!result.ok) failures.push(`${name} guarded ${signal} failed: ${result.error}`)
+      else {
+        if (result.matched && !result.signalSent) failures.push(`${name} guarded ${signal} matched but sent no signal`)
+        if (result.cutoff) target.dispatchCutoff = result.cutoff
       }
     }
 
     const sendStopSignal = (signal: NodeJS.Signals) => {
-      if (process.platform === "win32") {
-        // WSL-backed launches need a Linux signal first because the tracked Windows PID belongs to wsl.exe.
-        if (!trySignalWslProcess(signal)) {
-          // Fallback to the Windows process tree rooted at pid. Use /F only for escalation.
-          tryTaskkill(signal === "SIGKILL")
-        }
-        return
+      if (!pid) failures.push(`${signal} was not sent because the process PID is unavailable`)
+      if (pid && wrapperExited() && this.platform !== "linux" && this.platform !== "win32") refreshTargets()
+      let signaledOwnedGroup = false
+      if (pid && managed.identityCaptureFailed && this.platform !== "linux" && this.platform !== "win32" && !wrapperExited()) {
+        const result = signalOwnedPosixProcessGroup(this.spawnCommand, pid, signal, this.stopCommandTimeoutMs)
+        recordSignalResult(result, managed.targets!, "owned POSIX group", signal)
+        const leader = result.ok && result.matched ? result.signaled.find((identity) => identity.pid === pid) : undefined
+        if (leader) Object.assign(managed.targets!, { leader, groupId: pid })
+        refreshTargets()
+        signaledOwnedGroup = true
       }
-
-      // Prefer process-group signaling so wrapper launchers (bun/node) don't orphan the real server.
-      const groupOk = tryKillPosixGroup(signal)
-      if (!groupOk) {
-        // Fallback to direct PID kill.
-        tryKillSinglePid(signal)
+      if (pid && !signaledOwnedGroup) {
+        const target = trackedTarget()
+        const groupId = managed.wsl && hasWslIdentity() ? managed.wsl.linuxPgid! : target.groupId
+        const request = {
+          leader: trackedLeader(), groupId, members: [...target.members.values()], signal,
+          allowLeaderlessGroup: this.platform !== "linux" && this.platform !== "win32" &&
+            Boolean(target.groupOwnershipRetained && !target.groupGoneConfirmed && wrapperExited()),
+          cleanupToken: this.platform !== "linux" && this.platform !== "win32" ? managed.cleanupToken : undefined,
+        }
+        const result = managed.wsl && hasWslIdentity()
+          ? signalWslProcesses(this.spawnCommand, managed.wsl.distro, request, this.stopCommandTimeoutMs)
+          : this.platform === "win32"
+            ? signalWindowsProcesses(this.spawnCommand, request, this.stopCommandTimeoutMs)
+            : signalPosixProcesses(this.spawnCommand, request, this.stopCommandTimeoutMs, this.platform)
+        recordSignalResult(result, target, managed.wsl && hasWslIdentity() ? "WSL" : this.platform === "win32" ? "Windows" : "POSIX", signal)
+        refreshTargets()
+      }
+      if (usesTokenCleanup()) {
+        const result = signalLaunchCleanupToken(
+          this.spawnCommand, managed.cleanupToken, signal, this.stopCommandTimeoutMs, managed.wsl?.distro,
+        )
+        const name = managed.wsl ? "WSL" : "Linux"
+        if (!result.ok) failures.push(`${name} launch-token ${signal} failed: ${result.error}`)
+        else {
+          if (result.targets.length > 0 && !result.signalSent) failures.push(`${name} launch-token ${signal} matched but sent no signal`)
+          for (const identity of result.targets) trackedTarget().members.set(identity.pid, identity)
+        }
+        refreshTokenTargets()
       }
     }
 
-    await new Promise<void>((resolve, reject) => {
-      let escalationTimer: NodeJS.Timeout | null = null
-
-      const cleanup = () => {
-        child.removeListener("exit", onExit)
-        child.removeListener("error", onError)
-        if (escalationTimer) {
-          clearTimeout(escalationTimer)
-          escalationTimer = null
-        }
+    const probeLiveness = () => {
+      const refreshed = pid ? refreshTargets() : undefined
+      const tokenSnapshot = refreshTokenTargets()
+      if (tokenSnapshot && !tokenSnapshot.ok) {
+        return { state: "unknown", detail: `${managed.wsl ? "WSL Linux" : "Linux"} launch-token cleanup could not be confirmed` } as const
       }
-
-      const onExit = () => {
-        cleanup()
-        resolve()
+      if (refreshed && !refreshed.snapshot.ok && (managed.targets?.leader || !tokenSnapshot?.ok)) {
+        const name = managed.wsl ? "WSL Linux" : this.platform === "win32" ? "Windows" : "POSIX"
+        return { state: "unknown", detail: `${name} target identity could not be confirmed` } as const
       }
-      const onError = (error: Error) => {
-        cleanup()
-        reject(error)
+      if (managed.identityCaptureFailed && this.platform === "win32" && !managed.wsl) {
+        return { state: "unknown", detail: "Windows cleanup cannot prove exact launch ownership without a Job Object" } as const
       }
-
-      if (isAlreadyExited()) {
-        this.logger.debug({ workspaceId, exitCode: child.exitCode, signal: child.signalCode }, "Process already exited")
-        cleanup()
-        resolve()
-        return
+      if (managed.identityCaptureFailed && managed.wsl && !managed.targets?.leader && !wrapperExited()) {
+        return { state: "unknown", detail: "the unidentified Windows WSL wrapper is still alive" } as const
       }
-
-      child.once("exit", onExit)
-      child.once("error", onError)
-
-      this.logger.debug(
-        { workspaceId, pid, detached: process.platform !== "win32" },
-        "Sending SIGTERM to workspace process (tree/group)",
-      )
-      sendStopSignal("SIGTERM")
-
-      escalationTimer = setTimeout(() => {
-        escalationTimer = null
-        if (isAlreadyExited()) {
-          this.logger.debug({ workspaceId, pid }, "Workspace exited before SIGKILL escalation")
-          return
-        }
+      if (trackedTarget().groupOwnershipUncertain) {
+        return { state: "unknown", detail: "the retained POSIX process group no longer has a verified identity anchor" } as const
+      }
+      if (trackedTarget().members.size === 0) {
+        if (tokenSnapshot?.ok && tokenSnapshot.processes.size === 0) return { state: "gone", detail: "no process carries the unpublished launch token" } as const
+        return { state: "unknown", detail: pid ? "the original process identity was not captured" : "the target PID is unavailable" } as const
+      }
+      if ((refreshed?.aliveMembers.length ?? 0) === 0 && (!tokenSnapshot?.ok || tokenSnapshot.processes.size === 0)) {
+        return { state: "gone", detail: "all tracked original process identities are gone" } as const
+      }
+      const name = managed.wsl && hasWslIdentity() ? "WSL Linux process group" : this.platform === "win32" ? "Windows process tree" : "POSIX process group"
+      return { state: "alive", detail: `the tracked original ${name} is still alive` } as const
+    }
+    const stopped = () => probeLiveness().state === "gone" ? true : undefined
+    const totalTimeoutMs = this.gracefulStopTimeoutMs + this.forcedStopTimeoutMs
+    return this.runBoundedStop(workspaceId, managed, {
+      start: () => {
+        this.logger.debug({ workspaceId, pid, detached: this.platform !== "win32" }, "Sending SIGTERM to workspace process (tree/group)")
+        sendStopSignal("SIGTERM")
+        return stopped()
+      },
+      exit: stopped,
+      error: (error) => { failures.push(`child process error while stopping: ${error.message}`) },
+      escalate: () => {
+        const liveness = probeLiveness()
+        if (liveness.state === "gone") return true
         this.logger.warn({ workspaceId, pid }, "Process did not stop after SIGTERM, escalating")
         sendStopSignal("SIGKILL")
-      }, 2000)
+      },
+      deadline: () => {
+        const liveness = probeLiveness()
+        if (liveness.state === "gone") return true
+        const prefix = wrapperExited() ? "the wrapper exited but " : ""
+        return new WorkspaceStopTimeoutError(workspaceId, pid, totalTimeoutMs, `${prefix}${liveness.detail}`, failures)
+      },
+    })
+  }
+
+  private stopOwnedWindowsProcess(workspaceId: string, managed: ManagedProcess): Promise<void> {
+    const { child } = managed
+    const pid = child.pid
+    const failures = (managed.windowsTreeCleanupFailures ??= [])
+    const outcome = () => managed.windowsTreeCleanupConfirmed
+      ? true
+      : new WorkspaceWindowsTreeCleanupIncompleteError(workspaceId, pid, failures)
+    const stopChild = (force: boolean) => {
+      if (child.exitCode !== null || child.signalCode !== null) return
+      if (!pid) {
+        failures.push(`${force ? "forced" : "graceful"} stop was not sent because the process PID is unavailable`)
+        return
+      }
+      const args = ["/PID", String(pid), "/T", ...(force ? ["/F"] : [])]
+      try {
+        const result = this.spawnCommand("taskkill.exe", args, { encoding: "utf8", timeout: this.stopCommandTimeoutMs })
+        if (result.status === 0) managed.windowsTreeCleanupConfirmed = true
+        else {
+          const detail = result.error?.message || String(result.stderr ?? result.stdout ?? "").trim() || `exit code ${result.status}`
+          failures.push(`taskkill ${force ? "/T /F" : "/T"} failed: ${detail}`)
+        }
+      } catch (error) {
+        failures.push(`taskkill ${force ? "/T /F" : "/T"} failed: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+    const totalTimeoutMs = this.gracefulStopTimeoutMs + this.forcedStopTimeoutMs
+    return this.runBoundedStop(workspaceId, managed, {
+      start: () => {
+        if (child.exitCode !== null || child.signalCode !== null) return outcome()
+        this.logger.debug({ workspaceId, pid }, "Stopping owned Windows workspace wrapper tree")
+        stopChild(false)
+      },
+      exit: outcome,
+      error: (error) => {
+        failures.push(`child process error while stopping: ${error.message}`)
+        return error
+      },
+      escalate: () => {
+        this.logger.warn({ workspaceId, pid }, "Owned Windows process did not stop after the graceful attempt, escalating")
+        stopChild(true)
+      },
+      deadline: () => new WorkspaceStopTimeoutError(
+        workspaceId, pid, totalTimeoutMs,
+        child.exitCode !== null || child.signalCode !== null
+          ? "taskkill did not confirm tree cleanup before the owned Windows wrapper exited"
+          : "the owned Windows wrapper did not emit exit or error after tree termination",
+        failures,
+      ),
+    })
+  }
+
+  private runBoundedStop(
+    workspaceId: string,
+    managed: ManagedProcess,
+    actions: {
+      start: () => true | Error | void
+      exit: () => true | Error | void
+      error: (error: Error) => true | Error | void
+      escalate: () => true | Error | void
+      deadline: () => true | Error
+    },
+  ): Promise<void> {
+    const { child } = managed
+    return new Promise((resolve, reject) => {
+      let settled = false
+      const timers: RuntimeTimeout[] = []
+      const finish = (outcome: true | Error | void) => {
+        if (settled || !outcome) return
+        settled = true
+        child.removeListener("exit", onExit)
+        child.removeListener("error", onError)
+        for (const timer of timers) this.cancelTimeout(timer)
+        if (outcome instanceof Error) reject(outcome)
+        else {
+          if (this.processes.get(workspaceId) === managed) this.processes.delete(workspaceId)
+          managed.finalizeExit?.(child.exitCode, child.signalCode)
+          resolve()
+        }
+      }
+      const onExit = () => finish(actions.exit())
+      const onError = (error: Error) => finish(actions.error(error))
+      child.once("exit", onExit)
+      child.on("error", onError)
+      timers.push(this.scheduleTimeout(() => finish(actions.escalate()), this.gracefulStopTimeoutMs))
+      timers.push(this.scheduleTimeout(() => finish(actions.deadline()), this.gracefulStopTimeoutMs + this.forcedStopTimeoutMs))
+      finish(actions.start())
     })
   }
 
diff --git a/packages/server/src/workspaces/spawn.ts b/packages/server/src/workspaces/spawn.ts
index f40dcdb0..52ec18d7 100644
--- a/packages/server/src/workspaces/spawn.ts
+++ b/packages/server/src/workspaces/spawn.ts
@@ -1,4 +1,5 @@
 import { spawnSync } from "child_process"
+import { statSync } from "fs"
 import path from "path"
 
 export const WINDOWS_CMD_EXTENSIONS = new Set([".cmd", ".bat"])
@@ -13,10 +14,28 @@ const CODENOMAD_PLUGIN_FILE_SPEC_REGEX = new RegExp(
   `(${escapeRegex(CODENOMAD_PLUGIN_PACKAGE_NAME)}@file:)([A-Za-z]:[^"\\r\\n]+?\\.tgz)`,
 )
 const WSL_PATH_ENV_KEYS = new Set(["NODE_EXTRA_CA_CERTS", WSL_PLUGIN_PATH_ENV])
+const WINDOWS_DIRECT_EXTENSIONS = new Set([".com", ".exe"])
+const DEFAULT_WINDOWS_PATHEXT = ".COM;.EXE;.BAT;.CMD"
+const WINDOWS_SHELL_NAMES = new Set([
+  "bash",
+  "bash.exe",
+  "cmd",
+  "cmd.exe",
+  "command.com",
+  "powershell",
+  "powershell.exe",
+  "pwsh",
+  "pwsh.exe",
+  "sh",
+  "sh.exe",
+])
+
+export type SpawnProcessKind = "posix" | "windows-direct" | "windows-wrapper" | "wsl"
 
 export interface SpawnSpec {
   command: string
   args: string[]
+  processKind: SpawnProcessKind
   options: {
     windowsVerbatimArguments?: boolean
   }
@@ -33,6 +52,7 @@ interface BuildSpawnSpecOptions {
   env?: NodeJS.ProcessEnv
   propagateEnvKeys?: string[]
   wslPidMarker?: string
+  platform?: NodeJS.Platform
 }
 
 interface WslPath {
@@ -77,17 +97,21 @@ export function buildWindowsSpawnSpec(binaryPath: string, args: string[], option
     return buildWslSpawnSpec(wslPath, args, options)
   }
 
-  const extension = path.extname(binaryPath).toLowerCase()
+  const resolvedBinaryPath = resolveBareWindowsCommand(binaryPath, options) ?? binaryPath
+  const extension = path.win32.extname(resolvedBinaryPath).toLowerCase()
 
   if (WINDOWS_CMD_EXTENSIONS.has(extension)) {
-    const comspec = process.env.ComSpec || "cmd.exe"
+    const comspec = getWindowsEnvironmentValue(options.env, "COMSPEC") ??
+      getWindowsEnvironmentValue(process.env, "COMSPEC") ??
+      "cmd.exe"
     // cmd.exe requires the full command as a single string.
     // Using the ""<script> <args>"" pattern ensures paths with spaces are handled.
-    const commandLine = `""${binaryPath}" ${args.join(" ")}"`
+    const commandLine = `""${resolvedBinaryPath}" ${args.join(" ")}"`
 
     return {
       command: comspec,
       args: ["/d", "/s", "/c", commandLine],
+      processKind: "windows-wrapper",
       options: { windowsVerbatimArguments: true },
       cwd: options.cwd,
       env: options.env,
@@ -98,7 +122,8 @@ export function buildWindowsSpawnSpec(binaryPath: string, args: string[], option
     // powershell.exe ships with Windows. (pwsh may not.)
     return {
       command: "powershell.exe",
-      args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", binaryPath, ...args],
+      args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", resolvedBinaryPath, ...args],
+      processKind: "windows-wrapper",
       options: {},
       cwd: options.cwd,
       env: options.env,
@@ -106,8 +131,9 @@ export function buildWindowsSpawnSpec(binaryPath: string, args: string[], option
   }
 
   return {
-    command: binaryPath,
+    command: resolvedBinaryPath,
     args,
+    processKind: classifyWindowsCommand(resolvedBinaryPath),
     options: {},
     cwd: options.cwd,
     env: options.env,
@@ -115,10 +141,11 @@ export function buildWindowsSpawnSpec(binaryPath: string, args: string[], option
 }
 
 export function buildSpawnSpec(binaryPath: string, args: string[], options: BuildSpawnSpecOptions = {}): SpawnSpec {
-  if (process.platform !== "win32") {
+  if ((options.platform ?? process.platform) !== "win32") {
     return {
       command: binaryPath,
       args,
+      processKind: "posix",
       options: {},
       cwd: options.cwd,
       env: options.env,
@@ -128,15 +155,6 @@ export function buildSpawnSpec(binaryPath: string, args: string[], options: Buil
   return buildWindowsSpawnSpec(binaryPath, args, options)
 }
 
-export function buildWslSignalSpec(distro: string, linuxPid: number, signal: NodeJS.Signals): SpawnSpec {
-  return {
-    command: "wsl.exe",
-    args: ["--distribution", distro, "--exec", "kill", signal === "SIGKILL" ? "-KILL" : "-TERM", String(linuxPid)],
-    options: {},
-    wsl: { distro },
-  }
-}
-
 export function probeBinaryVersion(binaryPath: string): {
   valid: boolean
   version?: string
@@ -231,12 +249,73 @@ function buildWslSpawnSpec(wslPath: WslPath, args: string[], options: BuildSpawn
   return {
     command: "wsl.exe",
     args: wslArgs,
+    processKind: "wsl",
     options: {},
     env,
     wsl: { distro: wslPath.distro, pidMarker: options.wslPidMarker },
   }
 }
 
+function classifyWindowsCommand(binaryPath: string): SpawnProcessKind {
+  const commandName = path.win32.basename(binaryPath).toLowerCase()
+  if (WINDOWS_SHELL_NAMES.has(commandName)) {
+    return "windows-wrapper"
+  }
+
+  const extension = path.win32.extname(binaryPath).toLowerCase()
+  if (extension) {
+    return WINDOWS_DIRECT_EXTENSIONS.has(extension) ? "windows-direct" : "windows-wrapper"
+  }
+
+  // Bare commands can resolve to npm/script shims, so keep them on the
+  // wrapper path. That path owns cleanup without requiring process discovery.
+  return "windows-wrapper"
+}
+
+function resolveBareWindowsCommand(binaryPath: string, options: BuildSpawnSpecOptions): string | null {
+  if (!/^[^\\/:]+$/.test(binaryPath) || path.win32.extname(binaryPath)) return null
+
+  const env = options.env ?? process.env
+  const cwd = options.cwd ?? process.cwd()
+  const pathEntries = (getWindowsEnvironmentValue(env, "PATH") ?? "")
+    .split(";")
+    .map(unquoteWindowsPathEntry)
+  const extensions = (getWindowsEnvironmentValue(env, "PATHEXT") ?? DEFAULT_WINDOWS_PATHEXT)
+    .split(";")
+    .map((extension) => extension.trim())
+    .filter(Boolean)
+    .map((extension) => (extension.startsWith(".") ? extension : `.${extension}`).toLowerCase())
+
+  for (const entry of [cwd, ...pathEntries]) {
+    const directory = entry
+      ? path.win32.resolve(cwd, entry)
+      : path.win32.resolve(cwd)
+    for (const extension of extensions) {
+      const candidate = path.win32.join(directory, `${binaryPath}${extension}`)
+      try {
+        if (statSync(candidate).isFile()) return candidate
+      } catch {
+        // Continue in Windows PATH/PATHEXT order.
+      }
+    }
+  }
+
+  return null
+}
+
+function getWindowsEnvironmentValue(env: NodeJS.ProcessEnv | undefined, key: string): string | undefined {
+  if (!env) return undefined
+  const match = Object.keys(env).reverse().find((candidate) => candidate.toUpperCase() === key)
+  return match ? env[match] : undefined
+}
+
+function unquoteWindowsPathEntry(entry: string): string {
+  const trimmed = entry.trim()
+  return trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')
+    ? trimmed.slice(1, -1)
+    : trimmed
+}
+
 function buildWslLaunchScript(
   workingDirectory: WslWorkingDirectory | undefined,
   pidMarker: string | undefined,
@@ -245,7 +324,9 @@ function buildWslLaunchScript(
   const steps: string[] = []
 
   if (pidMarker) {
-    steps.push(`printf '%s%s\\n' '${pidMarker}' "$$"`)
+    steps.push(
+      `codenomad_pgid=$(ps -o pgid= -p "$$" 2>/dev/null | tr -d '[:space:]'); codenomad_start=$(awk '{print $22}' "/proc/$$/stat" 2>/dev/null); codenomad_boot=$(cat /proc/sys/kernel/random/boot_id 2>/dev/null); test -n "$codenomad_pgid" && test -n "$codenomad_start" && test -n "$codenomad_boot" && printf '%s%s:%s:%s:%s\\n' '${pidMarker}' "$$" "$codenomad_pgid" "$codenomad_start" "$codenomad_boot"`,
+    )
   }
 
   if (workingDirectory?.kind === "linux") {
diff --git a/packages/server/src/workspaces/workspace-identity.ts b/packages/server/src/workspaces/workspace-identity.ts
new file mode 100644
index 00000000..80307015
--- /dev/null
+++ b/packages/server/src/workspaces/workspace-identity.ts
@@ -0,0 +1,32 @@
+import { realpath, stat } from "node:fs/promises"
+import path from "node:path"
+
+export function normalizeWorkspaceIdentityPath(value: string, platform: NodeJS.Platform = process.platform): string {
+  const pathApi = platform === "win32" ? path.win32 : path.posix
+  const normalized = pathApi.normalize(value)
+  return platform === "win32" ? normalized.toLowerCase() : normalized
+}
+
+export async function resolveWorkspaceIdentity(
+  folder: string,
+  rootDir: string,
+): Promise<{ workspacePath: string; identityKey: string }> {
+  const submittedPath = path.isAbsolute(folder) ? path.normalize(folder) : path.resolve(rootDir, folder)
+
+  try {
+    const workspacePath = path.normalize(await realpath(submittedPath))
+    const metadata = await stat(workspacePath, { bigint: true })
+    return {
+      workspacePath,
+      identityKey: metadata.ino > 0n
+        ? `fs:${metadata.dev.toString()}:${metadata.ino.toString()}`
+        : normalizeWorkspaceIdentityPath(workspacePath),
+    }
+  } catch {
+    // Preserve the existing launch behavior when the path cannot be resolved yet.
+    return {
+      workspacePath: submittedPath,
+      identityKey: normalizeWorkspaceIdentityPath(submittedPath),
+    }
+  }
+}
diff --git a/packages/server/tsconfig.json b/packages/server/tsconfig.json
index 5f9cd234..8e9b5ce4 100644
--- a/packages/server/tsconfig.json
+++ b/packages/server/tsconfig.json
@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
-    "target": "ES2020",
+    "target": "ES2021",
     "module": "ESNext",
-    "moduleResolution": "Node",
+    "moduleResolution": "Bundler",
     "strict": true,
     "esModuleInterop": true,
     "resolveJsonModule": true,
diff --git a/packages/tauri-app/Cargo.lock b/packages/tauri-app/Cargo.lock
index 52242aad..9e381964 100644
--- a/packages/tauri-app/Cargo.lock
+++ b/packages/tauri-app/Cargo.lock
@@ -502,6 +502,7 @@ dependencies = [
  "anyhow",
  "base64 0.22.1",
  "dirs 5.0.1",
+ "fs2",
  "keepawake",
  "libc",
  "parking_lot",
@@ -517,8 +518,11 @@ dependencies = [
  "tauri-plugin-global-shortcut",
  "tauri-plugin-notification",
  "tauri-plugin-opener",
+ "tempfile",
  "url",
+ "uuid",
  "webkit2gtk",
+ "webview2-com",
  "which",
  "windows-sys 0.59.0",
 ]
@@ -1189,6 +1193,16 @@ dependencies = [
  "percent-encoding",
 ]
 
+[[package]]
+name = "fs2"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9564fc758e15025b46aa6643b1b77d047d1a56a1aea6e01002ac0c7026876213"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
 [[package]]
 name = "fs_extra"
 version = "1.3.0"
diff --git a/packages/tauri-app/src-tauri/Cargo.toml b/packages/tauri-app/src-tauri/Cargo.toml
index c94d775c..d99219a8 100644
--- a/packages/tauri-app/src-tauri/Cargo.toml
+++ b/packages/tauri-app/src-tauri/Cargo.toml
@@ -21,15 +21,19 @@ anyhow = "1"
 which = "4"
 libc = "0.2"
 keepawake = "0.6"
+fs2 = "0.4"
+tempfile = "3"
 tauri-plugin-dialog = "2"
 dirs = "5"
 tauri-plugin-opener = "2"
 tauri-plugin-global-shortcut = "2"
 url = "2"
+uuid = { version = "1", features = ["v4"] }
 tauri-plugin-notification = "2"
 
 [target.'cfg(windows)'.dependencies]
-windows-sys = { version = "0.59", features = ["Win32_Foundation", "Win32_Security_Cryptography", "Win32_UI_Shell", "Win32_Security", "Win32_System_JobObjects"] }
+webview2-com = "=0.38.2"
+windows-sys = { version = "0.59", features = ["Win32_Foundation", "Win32_Security_Cryptography", "Win32_UI_Shell", "Win32_UI_WindowsAndMessaging", "Win32_Security", "Win32_System_JobObjects", "Win32_System_Threading"] }
 
 [target.'cfg(target_os = "linux")'.dependencies]
 webkit2gtk = "2.0.2"
diff --git a/packages/tauri-app/src-tauri/src/cert_manager.rs b/packages/tauri-app/src-tauri/src/cert_manager.rs
index aea7ec55..c844e641 100644
--- a/packages/tauri-app/src-tauri/src/cert_manager.rs
+++ b/packages/tauri-app/src-tauri/src/cert_manager.rs
@@ -84,8 +84,7 @@ fn resolve_tls_asset_paths() -> Result<TlsAssetPaths, String> {
             })
         }
         (Some(_), None) | (None, Some(_)) => Err(
-            "CLI_TLS_KEY and CLI_TLS_CERT must both be set when using custom TLS files"
-                .to_string(),
+            "CLI_TLS_KEY and CLI_TLS_CERT must both be set when using custom TLS files".to_string(),
         ),
         (None, None) => {
             let tls_dir = server_tls_dir()?;
@@ -108,10 +107,12 @@ fn resolve_server_config_base_dir() -> Result<PathBuf, String> {
     let lower = raw.trim().to_lowercase();
 
     if lower.ends_with(".yaml") || lower.ends_with(".yml") || lower.ends_with(".json") {
-        return expanded
-            .parent()
-            .map(Path::to_path_buf)
-            .ok_or_else(|| format!("Failed to determine config base dir from {}", expanded.display()));
+        return expanded.parent().map(Path::to_path_buf).ok_or_else(|| {
+            format!(
+                "Failed to determine config base dir from {}",
+                expanded.display()
+            )
+        });
     }
 
     Ok(expanded)
@@ -239,8 +240,12 @@ pub fn trust_cert_in_store(cert_der: &[u8]) -> Result<(), String> {
         "codenomad-server-ca-{}.cer",
         trusted_marker_file_suffix(cert_der)
     ));
-    fs::write(&temp_path, cert_der)
-        .map_err(|e| format!("Failed to write temporary certificate {}: {e}", temp_path.display()))?;
+    fs::write(&temp_path, cert_der).map_err(|e| {
+        format!(
+            "Failed to write temporary certificate {}: {e}",
+            temp_path.display()
+        )
+    })?;
 
     let keychain_path = resolve_macos_user_keychain()?;
 
@@ -249,9 +254,7 @@ pub fn trust_cert_in_store(cert_der: &[u8]) -> Result<(), String> {
     command.arg(&keychain_path);
 
     let output = command.arg(&temp_path).output().map_err(|e| {
-        format!(
-            "Failed to launch macOS security tool to trust the local CA certificate: {e}"
-        )
+        format!("Failed to launch macOS security tool to trust the local CA certificate: {e}")
     })?;
 
     let _ = fs::remove_file(&temp_path);
@@ -328,7 +331,8 @@ fn resolve_macos_user_keychain() -> Result<PathBuf, String> {
     }
 
     let home = dirs::home_dir().or_else(|| env::var("HOME").ok().map(PathBuf::from));
-    let home = home.ok_or_else(|| "Cannot determine home directory for macOS keychain lookup".to_string())?;
+    let home = home
+        .ok_or_else(|| "Cannot determine home directory for macOS keychain lookup".to_string())?;
     Ok(home.join("Library/Keychains/login.keychain-db"))
 }
 
@@ -340,8 +344,12 @@ fn macos_cert_is_trusted(cert_der: &[u8]) -> Result<bool, String> {
         "codenomad-server-ca-verify-{}.cer",
         trusted_marker_file_suffix(cert_der)
     ));
-    fs::write(&temp_path, cert_der)
-        .map_err(|e| format!("Failed to write temporary certificate {}: {e}", temp_path.display()))?;
+    fs::write(&temp_path, cert_der).map_err(|e| {
+        format!(
+            "Failed to write temporary certificate {}: {e}",
+            temp_path.display()
+        )
+    })?;
 
     let keychain_path = resolve_macos_user_keychain()?;
     let fingerprint = macos_cert_sha256(&temp_path)?;
@@ -353,7 +361,9 @@ fn macos_cert_is_trusted(cert_der: &[u8]) -> Result<bool, String> {
 
     if !find_output.status.success() {
         let _ = fs::remove_file(&temp_path);
-        let stderr = String::from_utf8_lossy(&find_output.stderr).trim().to_string();
+        let stderr = String::from_utf8_lossy(&find_output.stderr)
+            .trim()
+            .to_string();
         let detail = if stderr.is_empty() {
             format!("security exited with status {}", find_output.status)
         } else {
@@ -376,7 +386,9 @@ fn macos_cert_is_trusted(cert_der: &[u8]) -> Result<bool, String> {
         .args(["-k"])
         .arg(&keychain_path)
         .output()
-        .map_err(|e| format!("Failed to verify macOS trust for the local CodeNomad CA certificate: {e}"))?;
+        .map_err(|e| {
+            format!("Failed to verify macOS trust for the local CodeNomad CA certificate: {e}")
+        })?;
 
     let _ = fs::remove_file(&temp_path);
     Ok(verify_output.status.success())
diff --git a/packages/tauri-app/src-tauri/src/cli_manager.rs b/packages/tauri-app/src-tauri/src/cli_manager.rs
index 00675684..78c42dd1 100644
--- a/packages/tauri-app/src-tauri/src/cli_manager.rs
+++ b/packages/tauri-app/src-tauri/src/cli_manager.rs
@@ -19,7 +19,7 @@ use std::net::TcpStream;
 use std::os::unix::process::CommandExt;
 use std::path::PathBuf;
 use std::process::{Child, Command, Stdio};
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::sync::Arc;
 use std::thread;
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
@@ -33,14 +33,17 @@ use std::os::windows::process::CommandExt;
 use windows_sys::Win32::Foundation::{CloseHandle, HANDLE};
 #[cfg(windows)]
 use windows_sys::Win32::System::JobObjects::{
-    AssignProcessToJobObject, CreateJobObjectW, JobObjectExtendedLimitInformation,
-    SetInformationJobObject, JOBOBJECT_EXTENDED_LIMIT_INFORMATION,
-    JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
+    AssignProcessToJobObject, CreateJobObjectW, JobObjectBasicAccountingInformation,
+    JobObjectExtendedLimitInformation, QueryInformationJobObject, SetInformationJobObject,
+    TerminateJobObject, JOBOBJECT_BASIC_ACCOUNTING_INFORMATION,
+    JOBOBJECT_EXTENDED_LIMIT_INFORMATION, JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
 };
 
 #[cfg(windows)]
 const CREATE_NO_WINDOW: u32 = 0x08000000;
 const MISSING_NODE_PREFIX: &str = "CODENOMAD_MISSING_NODE:";
+#[cfg(windows)]
+const CLI_SHUTDOWN_COMMAND: &[u8] = b"codenomad:shutdown\n";
 
 #[cfg(windows)]
 #[derive(Debug)]
@@ -96,6 +99,36 @@ impl WindowsJobObject {
 
         Ok(())
     }
+
+    fn active_processes(&self) -> anyhow::Result<u32> {
+        let mut info: JOBOBJECT_BASIC_ACCOUNTING_INFORMATION = unsafe { zeroed() };
+        let ok = unsafe {
+            QueryInformationJobObject(
+                self.handle,
+                JobObjectBasicAccountingInformation,
+                &mut info as *mut _ as *mut c_void,
+                size_of::<JOBOBJECT_BASIC_ACCOUNTING_INFORMATION>() as u32,
+                std::ptr::null_mut(),
+            )
+        };
+        if ok == 0 {
+            return Err(anyhow::anyhow!(
+                "QueryInformationJobObject failed: {}",
+                std::io::Error::last_os_error()
+            ));
+        }
+        Ok(info.ActiveProcesses)
+    }
+
+    fn terminate(&self) -> anyhow::Result<()> {
+        if unsafe { TerminateJobObject(self.handle, 1) } == 0 {
+            return Err(anyhow::anyhow!(
+                "TerminateJobObject failed: {}",
+                std::io::Error::last_os_error()
+            ));
+        }
+        Ok(())
+    }
 }
 
 #[cfg(windows)]
@@ -140,9 +173,11 @@ fn workspace_root() -> Option<PathBuf> {
 
 const SESSION_COOKIE_NAME_PREFIX: &str = "codenomad_session";
 
+#[cfg(not(windows))]
 const CLI_STOP_GRACE_SECS: u64 = 30;
 #[cfg(windows)]
 const CLI_WINDOWS_FORCE_GRACE_MS: u64 = 2_000;
+const CLI_FORCE_CONFIRM_GRACE_SECS: u64 = 2;
 
 #[cfg(unix)]
 fn configure_posix_process_group(command: &mut Command) {
@@ -159,33 +194,219 @@ fn configure_posix_process_group(command: &mut Command) {
 }
 
 #[cfg(windows)]
-fn kill_process_tree_windows(pid: u32, force: bool) -> bool {
-    let mut args = vec!["/PID".to_string(), pid.to_string(), "/T".to_string()];
-    if force {
-        args.push("/F".to_string());
+const WINDOWS_CLI_LAUNCHER_ARG: &str = "--codenomad-internal-cli-launcher";
+
+#[cfg(windows)]
+fn wait_for_windows_cli_launch_gate(mut reader: impl Read) -> bool {
+    let mut gate = [0_u8; 1];
+    reader.read_exact(&mut gate).is_ok() && gate[0] == 1
+}
+
+#[cfg(windows)]
+fn relay_windows_cli_control(
+    mut reader: impl Read,
+    mut writer: impl Write,
+) -> std::io::Result<u64> {
+    std::io::copy(&mut reader, &mut writer)
+}
+
+#[cfg(windows)]
+fn request_windows_cli_shutdown(writer: &mut impl Write) -> std::io::Result<()> {
+    writer.write_all(CLI_SHUTDOWN_COMMAND)?;
+    writer.flush()
+}
+
+#[cfg(windows)]
+pub(crate) fn run_windows_cli_launcher_if_requested() -> Option<i32> {
+    let mut args = std::env::args_os();
+    args.next();
+    if args.next()?.to_str()? != WINDOWS_CLI_LAUNCHER_ARG {
+        return None;
+    }
+    let Some(program) = args.next() else {
+        return Some(1);
+    };
+    if !wait_for_windows_cli_launch_gate(std::io::stdin().lock()) {
+        return Some(1);
     }
 
-    let mut command = Command::new("taskkill");
-    command.args(&args);
+    let mut command = Command::new(program);
+    command.args(args);
+    command.stdin(Stdio::piped());
     configure_spawn(&mut command);
+    let Ok(mut child) = command.spawn() else {
+        return Some(1);
+    };
+    if let Some(mut node_stdin) = child.stdin.take() {
+        thread::spawn(move || {
+            let stdin = std::io::stdin();
+            let _ = relay_windows_cli_control(stdin.lock(), &mut node_stdin);
+        });
+    }
+    Some(
+        child
+            .wait()
+            .ok()
+            .and_then(|status| status.code())
+            .unwrap_or(1),
+    )
+}
 
-    match command.output() {
-        Ok(output) => {
-            if output.status.success() {
-                return true;
-            }
+#[cfg(windows)]
+fn windows_containment_confirmed(child_exited: bool, job_active_processes: Option<u32>) -> bool {
+    child_exited && job_active_processes == Some(0)
+}
 
-            // If the PID is already gone, treat it as success.
-            let stdout = String::from_utf8_lossy(&output.stdout).to_lowercase();
-            let stderr = String::from_utf8_lossy(&output.stderr).to_lowercase();
-            let combined = format!("{stdout}\n{stderr}");
-            combined.contains("not found") || combined.contains("no running instance")
+fn wait_for_termination(
+    timeout: Duration,
+    poll_interval: Duration,
+    mut is_terminated: impl FnMut() -> anyhow::Result<bool>,
+) -> anyhow::Result<()> {
+    let deadline = Instant::now() + timeout;
+    loop {
+        if is_terminated()? {
+            return Ok(());
         }
-        Err(_) => false,
+        if Instant::now() >= deadline {
+            return Err(TerminationTimeout.into());
+        }
+        thread::sleep(poll_interval.min(deadline.saturating_duration_since(Instant::now())));
     }
 }
-fn navigate_main(app: &AppHandle, url: &str) {
-    if let Some(win) = app.webview_windows().get("main") {
+
+#[derive(Debug)]
+struct TerminationTimeout;
+
+impl std::fmt::Display for TerminationTimeout {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str("process termination was not confirmed")
+    }
+}
+
+impl std::error::Error for TerminationTimeout {}
+
+fn containment_is_complete(root_exited: bool, descendants_gone: bool) -> bool {
+    root_exited && descendants_gone
+}
+
+#[cfg(unix)]
+fn process_group_is_gone(pid: u32) -> anyhow::Result<bool> {
+    if unsafe { libc::kill(-(pid as i32), 0) } == 0 {
+        return Ok(false);
+    }
+    match std::io::Error::last_os_error().raw_os_error() {
+        Some(libc::ESRCH) => Ok(true),
+        Some(libc::EPERM) => Ok(false),
+        _ => Err(anyhow::anyhow!(
+            "failed to inspect CLI process group {pid}: {}",
+            std::io::Error::last_os_error()
+        )),
+    }
+}
+
+fn stop_child(
+    child: &mut Child,
+    #[cfg(windows)] job: Option<&WindowsJobObject>,
+) -> anyhow::Result<()> {
+    let pid = child.id();
+    #[cfg(windows)]
+    if job.is_none() {
+        if child.try_wait()?.is_none() {
+            let _ = child.kill();
+            let _ = wait_for_termination(
+                Duration::from_secs(CLI_FORCE_CONFIRM_GRACE_SECS),
+                Duration::from_millis(25),
+                || Ok(child.try_wait()?.is_some()),
+            );
+        }
+        return Err(anyhow::anyhow!(
+            "CLI pid={pid} descendant cleanup cannot be confirmed without a Windows job"
+        ));
+    }
+
+    #[cfg(unix)]
+    unsafe {
+        if libc::kill(-(pid as i32), libc::SIGTERM) != 0 {
+            let _ = libc::kill(pid as i32, libc::SIGTERM);
+        }
+    }
+    #[cfg(windows)]
+    let graceful_timeout = Duration::from_millis(CLI_WINDOWS_FORCE_GRACE_MS);
+    #[cfg(not(windows))]
+    let graceful_timeout = Duration::from_secs(CLI_STOP_GRACE_SECS);
+    #[cfg(windows)]
+    if child.try_wait()?.is_none() {
+        match child.stdin.take() {
+            Some(mut control) => {
+                if let Err(err) = request_windows_cli_shutdown(&mut control) {
+                    log_line(&format!(
+                        "failed to request graceful CLI shutdown pid={pid}: {err}"
+                    ));
+                }
+            }
+            None => log_line(&format!("CLI control channel is unavailable pid={pid}")),
+        }
+    }
+    let graceful = wait_for_termination(graceful_timeout, Duration::from_millis(50), || {
+        let child_exited = child.try_wait()?.is_some();
+        #[cfg(unix)]
+        return Ok(child_exited && process_group_is_gone(pid)?);
+        #[cfg(windows)]
+        return Ok(windows_containment_confirmed(
+            child_exited,
+            job.map(WindowsJobObject::active_processes).transpose()?,
+        ));
+        #[cfg(not(any(unix, windows)))]
+        Ok(child_exited)
+    });
+    match graceful {
+        Ok(()) => return Ok(()),
+        Err(err) if !err.is::<TerminationTimeout>() => {
+            return Err(anyhow::anyhow!(
+                "failed to inspect CLI pid={pid} termination: {err}"
+            ))
+        }
+        Err(_) => {}
+    }
+
+    log_line(&format!("CLI shutdown timed out; escalating pid={pid}"));
+    #[cfg(unix)]
+    unsafe {
+        if libc::kill(-(pid as i32), libc::SIGKILL) != 0 {
+            let _ = libc::kill(pid as i32, libc::SIGKILL);
+        }
+    }
+    #[cfg(windows)]
+    {
+        job.expect("Windows job checked above").terminate()?;
+    }
+    #[cfg(not(any(unix, windows)))]
+    child.kill()?;
+
+    wait_for_termination(
+        Duration::from_secs(CLI_FORCE_CONFIRM_GRACE_SECS),
+        Duration::from_millis(25),
+        || {
+            let child_exited = child.try_wait()?.is_some();
+            #[cfg(unix)]
+            return Ok(child_exited && process_group_is_gone(pid)?);
+            #[cfg(windows)]
+            return Ok(windows_containment_confirmed(
+                child_exited,
+                job.map(WindowsJobObject::active_processes).transpose()?,
+            ));
+            #[cfg(not(any(unix, windows)))]
+            Ok(child_exited)
+        },
+    )
+    .map_err(|err| anyhow::anyhow!("CLI pid={pid} termination was not confirmed: {err}"))
+}
+
+fn navigate_main(manager: &CliProcessManager, generation: u64, app: &AppHandle, url: &str) {
+    if !manager.is_current_generation(generation) {
+        return;
+    }
+    if app.webview_windows().contains_key("main") {
         let final_url = augment_launch_url(url);
         let mut display = final_url.clone();
         if let Some(hash_index) = display.find('#') {
@@ -193,7 +414,26 @@ fn navigate_main(app: &AppHandle, url: &str) {
         }
         log_line(&format!("navigating main to {display}"));
         if let Ok(parsed) = Url::parse(&final_url) {
-            let _ = win.navigate(parsed);
+            let current = manager.clone();
+            let navigate = manager.clone();
+            crate::client_state::before_main_window_navigation_if(
+                app,
+                crate::client_state::NavigationKind::Cli,
+                Some(parsed.clone()),
+                move || current.is_current_generation(generation),
+                move |app| {
+                    navigate
+                        .with_current_generation(generation, || {
+                            let window = app.get_webview_window("main").ok_or_else(|| {
+                                "main window not found for CLI navigation".to_string()
+                            })?;
+                            window.navigate(parsed).map_err(|err| {
+                                format!("failed to navigate main window to CLI URL: {err}")
+                            })
+                        })
+                        .unwrap_or_else(|| Err("discarded stale CLI navigation".to_string()))
+                },
+            );
         } else {
             log_line("failed to parse URL for navigation");
         }
@@ -490,10 +730,11 @@ pub struct CliProcessManager {
     child: Arc<Mutex<Option<Child>>>,
     #[cfg(windows)]
     job: Arc<Mutex<Option<WindowsJobObject>>>,
-    ready: Arc<AtomicBool>,
     bootstrap_token: Arc<Mutex<Option<String>>>,
     session_cookie: Arc<Mutex<Option<String>>>,
     auth_cookie_name: Arc<Mutex<Option<String>>>,
+    lifecycle: Arc<Mutex<()>>,
+    generation: Arc<AtomicU64>,
 }
 
 impl CliProcessManager {
@@ -503,17 +744,19 @@ impl CliProcessManager {
             child: Arc::new(Mutex::new(None)),
             #[cfg(windows)]
             job: Arc::new(Mutex::new(None)),
-            ready: Arc::new(AtomicBool::new(false)),
             bootstrap_token: Arc::new(Mutex::new(None)),
             session_cookie: Arc::new(Mutex::new(None)),
             auth_cookie_name: Arc::new(Mutex::new(None)),
+            lifecycle: Arc::new(Mutex::new(())),
+            generation: Arc::new(AtomicU64::new(0)),
         }
     }
 
     pub fn start(&self, app: AppHandle, dev: bool) -> anyhow::Result<()> {
+        let _lifecycle = self.lifecycle.lock();
+        let generation = self.advance_generation();
         log_line(&format!("start requested (dev={dev})"));
-        self.stop()?;
-        self.ready.store(false, Ordering::SeqCst);
+        self.stop_tracked_child()?;
         *self.bootstrap_token.lock() = None;
         *self.session_cookie.lock() = None;
         *self.auth_cookie_name.lock() = None;
@@ -527,35 +770,11 @@ impl CliProcessManager {
         }
         Self::emit_status(&app, &self.status.lock());
 
-        let status_arc = self.status.clone();
-        let child_arc = self.child.clone();
-        #[cfg(windows)]
-        let job_arc = self.job.clone();
-        let ready_flag = self.ready.clone();
-        let token_arc = self.bootstrap_token.clone();
-        let session_cookie_arc = self.session_cookie.clone();
-        let auth_cookie_name_arc = self.auth_cookie_name.clone();
+        let manager = self.clone();
         thread::spawn(move || {
-            if let Err(err) = Self::spawn_cli(
-                app.clone(),
-                status_arc.clone(),
-                child_arc,
-                #[cfg(windows)]
-                job_arc,
-                ready_flag,
-                token_arc,
-                session_cookie_arc,
-                auth_cookie_name_arc,
-                dev,
-            ) {
+            if let Err(err) = Self::spawn_cli(manager.clone(), app.clone(), generation, dev) {
                 log_line(&format!("cli spawn failed: {err}"));
-                let mut locked = status_arc.lock();
-                locked.state = CliState::Error;
-                locked.error = Some(err.to_string());
-                let snapshot = locked.clone();
-                drop(locked);
-                let _ = app.emit("cli:error", json!({"message": err.to_string()}));
-                let _ = app.emit("cli:status", snapshot);
+                manager.publish_error(&app, generation, err.to_string());
             }
         });
 
@@ -563,77 +782,73 @@ impl CliProcessManager {
     }
 
     pub fn stop(&self) -> anyhow::Result<()> {
-        #[cfg(windows)]
-        let _job = self.job.lock().take();
+        let _lifecycle = self.lifecycle.lock();
+        self.advance_generation();
+        self.stop_tracked_child()?;
+        self.reset_stopped_status();
+        Ok(())
+    }
 
-        let mut child_opt = self.child.lock();
-        if let Some(mut child) = child_opt.take() {
-            log_line(&format!("stopping CLI pid={}", child.id()));
-            #[cfg(unix)]
-            unsafe {
-                let pid = child.id() as i32;
-                // Prefer signaling the process group to avoid orphaning children
-                // when the CLI was launched via a wrapper shell.
-                let group_res = libc::kill(-pid, libc::SIGTERM);
-                if group_res != 0 {
-                    let _ = libc::kill(pid, libc::SIGTERM);
+    fn advance_generation(&self) -> u64 {
+        self.generation.fetch_add(1, Ordering::SeqCst) + 1
+    }
+
+    fn is_current_generation(&self, generation: u64) -> bool {
+        self.generation.load(Ordering::SeqCst) == generation
+    }
+
+    fn with_current_generation<T>(
+        &self,
+        generation: u64,
+        operation: impl FnOnce() -> T,
+    ) -> Option<T> {
+        let _lifecycle = self.lock_current_generation(generation)?;
+        Some(operation())
+    }
+
+    fn lock_current_generation(&self, generation: u64) -> Option<parking_lot::MutexGuard<'_, ()>> {
+        let lifecycle = self.lifecycle.lock();
+        self.is_current_generation(generation).then_some(lifecycle)
+    }
+
+    fn stop_tracked_child(&self) -> anyhow::Result<()> {
+        let Some(mut child) = self.child.lock().take() else {
+            #[cfg(windows)]
+            if let Some(job) = self.job.lock().take() {
+                let result = job.terminate().and_then(|()| {
+                    wait_for_termination(
+                        Duration::from_secs(CLI_FORCE_CONFIRM_GRACE_SECS),
+                        Duration::from_millis(25),
+                        || Ok(job.active_processes()? == 0),
+                    )
+                });
+                if let Err(err) = result {
+                    *self.job.lock() = Some(job);
+                    return Err(err);
                 }
             }
+            return Ok(());
+        };
+        #[cfg(windows)]
+        let job = self.job.lock().take();
+        log_line(&format!("stopping CLI pid={}", child.id()));
+        let result = stop_child(
+            &mut child,
+            #[cfg(windows)]
+            job.as_ref(),
+        );
+        if let Err(err) = result {
+            *self.child.lock() = Some(child);
             #[cfg(windows)]
             {
-                let _ = kill_process_tree_windows(child.id(), false);
+                *self.job.lock() = job;
             }
-
-            let start = Instant::now();
-            loop {
-                match child.try_wait() {
-                    Ok(Some(_)) => break,
-                    Ok(None) => {
-                        #[cfg(windows)]
-                        if start.elapsed() > Duration::from_millis(CLI_WINDOWS_FORCE_GRACE_MS) {
-                            log_line(&format!(
-                                "regular Windows shutdown still running after {}ms; escalating pid={}",
-                                CLI_WINDOWS_FORCE_GRACE_MS,
-                                child.id()
-                            ));
-                            if !kill_process_tree_windows(child.id(), true) {
-                                let _ = child.kill();
-                            }
-                            break;
-                        }
-
-                        if start.elapsed() > Duration::from_secs(CLI_STOP_GRACE_SECS) {
-                            log_line(&format!(
-                                "stop timed out after {}s; sending SIGKILL pid={}",
-                                CLI_STOP_GRACE_SECS,
-                                child.id()
-                            ));
-                            #[cfg(unix)]
-                            unsafe {
-                                let pid = child.id() as i32;
-                                let group_res = libc::kill(-pid, libc::SIGKILL);
-                                if group_res != 0 {
-                                    let _ = libc::kill(pid, libc::SIGKILL);
-                                }
-                            }
-                            #[cfg(windows)]
-                            {
-                                if !kill_process_tree_windows(child.id(), true) {
-                                    let _ = child.kill();
-                                }
-                            }
-                            break;
-                        }
-                        thread::sleep(Duration::from_millis(50));
-                    }
-                    Err(_) => break,
-                }
-            }
-        } else {
-            #[cfg(windows)]
-            log_line("tracked CLI process already exited; dropping Windows job object to reap descendants");
+            return Err(err);
         }
+        Ok(())
+    }
 
+    fn reset_stopped_status(&self) {
         let mut status = self.status.lock();
         status.state = CliState::Stopped;
         status.pid = None;
@@ -641,8 +856,18 @@ impl CliProcessManager {
         status.url = None;
         status.error = None;
         *self.session_cookie.lock() = None;
+    }
 
-        Ok(())
+    fn publish_error(&self, app: &AppHandle, generation: u64, message: String) {
+        self.with_current_generation(generation, || {
+            let mut status = self.status.lock();
+            status.state = CliState::Error;
+            status.error = Some(message.clone());
+            let snapshot = status.clone();
+            drop(status);
+            let _ = app.emit("cli:error", json!({"message": message}));
+            let _ = app.emit("cli:status", snapshot);
+        });
     }
 
     pub fn status(&self) -> CliStatus {
@@ -670,16 +895,14 @@ impl CliProcessManager {
     }
 
     fn spawn_cli(
+        manager: CliProcessManager,
         app: AppHandle,
-        status: Arc<Mutex<CliStatus>>,
-        child_holder: Arc<Mutex<Option<Child>>>,
-        #[cfg(windows)] job_holder: Arc<Mutex<Option<WindowsJobObject>>>,
-        ready: Arc<AtomicBool>,
-        bootstrap_token: Arc<Mutex<Option<String>>>,
-        session_cookie: Arc<Mutex<Option<String>>>,
-        auth_cookie_name_holder: Arc<Mutex<Option<String>>>,
+        generation: u64,
         dev: bool,
     ) -> anyhow::Result<()> {
+        let Some(lifecycle) = manager.lock_current_generation(generation) else {
+            return Ok(());
+        };
         log_line("resolving CLI entry");
         let resolution = CliEntry::resolve(&app, dev)?;
         let host = resolve_listening_host();
@@ -688,7 +911,6 @@ impl CliProcessManager {
             resolution.runner, resolution.entry, host
         ));
         let auth_cookie_name = Arc::new(generate_auth_cookie_name());
-        *auth_cookie_name_holder.lock() = Some(auth_cookie_name.as_str().to_string());
         let args = resolution.build_args(dev, &host, auth_cookie_name.as_str());
         log_line(&format!("CLI args: {:?}", args));
         if dev {
@@ -724,7 +946,7 @@ impl CliProcessManager {
             })
         };
 
-        let child = match &command_info {
+        let mut child = match &command_info {
             ShellCommandType::UserShell(cmd) => {
                 log_line(&format!("spawn command: {} {:?}", cmd.shell, cmd.args));
                 let mut c = Command::new(&cmd.shell);
@@ -744,9 +966,23 @@ impl CliProcessManager {
             }
             ShellCommandType::Direct(cmd) => {
                 log_line(&format!("spawn command: {} {:?}", cmd.program, cmd.args));
+                #[cfg(windows)]
+                let mut c = {
+                    // The launcher cannot create Node until its stdin gate opens. Assigning
+                    // the blocked launcher first makes every later descendant inherit the job.
+                    let mut launcher = Command::new(std::env::current_exe()?);
+                    launcher
+                        .arg(WINDOWS_CLI_LAUNCHER_ARG)
+                        .arg(&cmd.program)
+                        .args(&cmd.args)
+                        .stdin(Stdio::piped());
+                    launcher
+                };
+                #[cfg(not(windows))]
                 let mut c = Command::new(&cmd.program);
-                c.args(&cmd.args)
-                    .env("ELECTRON_RUN_AS_NODE", "1")
+                #[cfg(not(windows))]
+                c.args(&cmd.args);
+                c.env("ELECTRON_RUN_AS_NODE", "1")
                     .stdout(Stdio::piped())
                     .stderr(Stdio::piped());
                 configure_spawn(&mut c);
@@ -762,201 +998,193 @@ impl CliProcessManager {
         let pid = child.id();
         log_line(&format!("spawned pid={pid}"));
         #[cfg(windows)]
-        match WindowsJobObject::create().and_then(|job| {
+        let job = match WindowsJobObject::create().and_then(|job| {
             job.assign_child(&child)?;
             Ok(job)
         }) {
             Ok(job) => {
                 log_line(&format!("attached pid={pid} to Windows job object"));
-                *job_holder.lock() = Some(job);
+                job
             }
             Err(err) => {
-                log_line(&format!(
-                    "failed to attach pid={pid} to Windows job object; falling back to taskkill-only cleanup: {err}"
+                let _ = child.kill();
+                let _ = child.wait();
+                return Err(anyhow::anyhow!(
+                    "failed to contain blocked CLI launcher pid={pid}; launch cancelled: {err}"
                 ));
             }
-        }
-
-        {
-            let mut locked = status.lock();
-            locked.pid = Some(pid);
-        }
-        Self::emit_status(&app, &status.lock());
-
-        {
-            let mut holder = child_holder.lock();
-            *holder = Some(child);
-        }
-
-        let child_clone = child_holder.clone();
-        let status_clone = status.clone();
-        let app_clone = app.clone();
-        let ready_clone = ready.clone();
-        let token_clone = bootstrap_token.clone();
-        let session_cookie_clone = session_cookie.clone();
-        let auth_cookie_name_clone = auth_cookie_name.clone();
-
-        thread::spawn(move || {
-            let stdout = child_clone
-                .lock()
-                .as_mut()
-                .and_then(|c| c.stdout.take())
-                .map(BufReader::new);
-            let stderr = child_clone
-                .lock()
-                .as_mut()
-                .and_then(|c| c.stderr.take())
-                .map(BufReader::new);
-
-            if let Some(reader) = stdout {
-                let app = app_clone.clone();
-                let status = status_clone.clone();
-                let ready = ready_clone.clone();
-                let token = token_clone.clone();
-                let session_cookie = session_cookie_clone.clone();
-                let auth_cookie_name = auth_cookie_name_clone.clone();
-                thread::spawn(move || {
-                    Self::process_stream(
-                        reader,
-                        "stdout",
-                        &app,
-                        &status,
-                        &ready,
-                        &token,
-                        &session_cookie,
-                        auth_cookie_name.as_str(),
-                    );
-                });
-            }
-
-            if let Some(reader) = stderr {
-                let app = app_clone.clone();
-                let status = status_clone.clone();
-                let ready = ready_clone.clone();
-                let token = token_clone.clone();
-                let session_cookie = session_cookie_clone.clone();
-                let auth_cookie_name = auth_cookie_name_clone.clone();
-                thread::spawn(move || {
-                    Self::process_stream(
-                        reader,
-                        "stderr",
-                        &app,
-                        &status,
-                        &ready,
-                        &token,
-                        &session_cookie,
-                        auth_cookie_name.as_str(),
-                    );
-                });
-            }
-        });
-
-        let app_clone = app.clone();
-        let status_clone = status.clone();
-        let ready_clone = ready.clone();
-        let child_holder_clone = child_holder.clone();
+        };
         #[cfg(windows)]
-        let job_holder_clone = job_holder.clone();
-        thread::spawn(move || {
-            let timeout = Duration::from_secs(60);
-            thread::sleep(timeout);
-            if ready_clone.load(Ordering::SeqCst) {
-                return;
-            }
-            let mut locked = status_clone.lock();
-            locked.state = CliState::Error;
-            locked.error = Some("CLI did not start in time".to_string());
-            log_line("timeout waiting for CLI readiness");
-            if let Some(child) = child_holder_clone.lock().as_mut() {
-                #[cfg(unix)]
-                unsafe {
-                    let pid = child.id() as i32;
-                    let group_res = libc::kill(-pid, libc::SIGKILL);
-                    if group_res != 0 {
-                        let _ = libc::kill(pid, libc::SIGKILL);
-                    }
-                }
-                #[cfg(windows)]
-                {
-                    if !kill_process_tree_windows(child.id(), true) {
-                        let _ = child.kill();
-                    }
-                }
-                #[cfg(not(any(unix, windows)))]
-                {
-                    let _ = child.kill();
-                }
-            }
-            let _ = app_clone.emit("cli:error", json!({"message": "CLI did not start in time"}));
-            Self::emit_status(&app_clone, &locked);
-        });
-
-        let status_clone = status.clone();
-        let app_clone = app.clone();
-        thread::spawn(move || {
-            // Do not hold the child mutex while waiting for process exit.
-            // Holding the lock across `wait()` deadlocks `stop()`, which needs the
-            // same lock to send SIGTERM/SIGKILL when the user quits the app.
-            let code = loop {
-                let maybe_exited = {
-                    let mut guard = child_holder.lock();
-                    if guard.is_none() {
-                        return;
-                    }
-                    match guard
-                        .as_mut()
-                        .and_then(|child| child.try_wait().ok().flatten())
-                    {
-                        Some(status) => {
-                            // Drop the handle after the process exits so other callers
-                            // don't attempt to stop/kill a finished process.
-                            *guard = None;
-                            #[cfg(windows)]
-                            {
-                                let _ = job_holder_clone.lock().take();
-                            }
-                            Some(status)
-                        }
-                        None => None,
-                    }
-                };
-
-                if let Some(status) = maybe_exited {
-                    break Some(status);
-                }
-                thread::sleep(Duration::from_millis(100));
-            };
-
-            let mut locked = status_clone.lock();
-            let failed = locked.state != CliState::Ready;
-            let err_msg = if failed {
-                Some(match code {
-                    Some(status) => format!("CLI exited early: {status}"),
-                    None => "CLI exited early".to_string(),
-                })
-            } else {
-                None
-            };
-
-            if failed {
-                locked.state = CliState::Error;
-                if locked.error.is_none() {
-                    locked.error = err_msg.clone();
-                }
-                log_line(&format!(
-                    "cli process exited before ready: {:?}",
-                    locked.error
+        {
+            let gate_result = child
+                .stdin
+                .as_mut()
+                .ok_or_else(|| anyhow::anyhow!("blocked CLI launcher stdin is unavailable"))
+                .and_then(|gate| {
+                    gate.write_all(&[1])?;
+                    gate.flush().map_err(anyhow::Error::from)
+                });
+            if let Err(err) = gate_result {
+                let _ = job.terminate();
+                let _ = child.kill();
+                let _ = child.wait();
+                return Err(anyhow::anyhow!(
+                    "failed to release contained CLI launcher pid={pid}: {err}"
                 ));
-                let _ = app_clone.emit(
-                    "cli:error",
-                    json!({"message": locked.error.clone().unwrap_or_default()}),
-                );
-            } else {
-                locked.state = CliState::Stopped;
-                log_line("cli process stopped cleanly");
             }
+        }
 
-            Self::emit_status(&app_clone, &locked);
+        let stdout = child.stdout.take().map(BufReader::new);
+        let stderr = child.stderr.take().map(BufReader::new);
+        debug_assert!(manager.child.lock().is_none());
+        *manager.auth_cookie_name.lock() = Some(auth_cookie_name.as_str().to_string());
+        manager.status.lock().pid = Some(pid);
+        *manager.child.lock() = Some(child);
+        #[cfg(windows)]
+        {
+            *manager.job.lock() = Some(job);
+        }
+        Self::emit_status(&app, &manager.status.lock());
+        drop(lifecycle);
+
+        let ready = Arc::new(AtomicBool::new(false));
+        if let Some(reader) = stdout {
+            let app = app.clone();
+            let manager = manager.clone();
+            let ready = ready.clone();
+            let auth_cookie_name = auth_cookie_name.clone();
+            thread::spawn(move || {
+                Self::process_stream(
+                    reader,
+                    "stdout",
+                    &manager,
+                    generation,
+                    &app,
+                    &ready,
+                    auth_cookie_name.as_str(),
+                );
+            });
+        }
+        if let Some(reader) = stderr {
+            let app = app.clone();
+            let manager = manager.clone();
+            let ready = ready.clone();
+            let auth_cookie_name = auth_cookie_name.clone();
+            thread::spawn(move || {
+                Self::process_stream(
+                    reader,
+                    "stderr",
+                    &manager,
+                    generation,
+                    &app,
+                    &ready,
+                    auth_cookie_name.as_str(),
+                );
+            });
+        }
+
+        {
+            let manager = manager.clone();
+            let app = app.clone();
+            let ready = ready.clone();
+            thread::spawn(move || {
+                thread::sleep(Duration::from_secs(60));
+                let _lifecycle = manager.lifecycle.lock();
+                if !manager.is_current_generation(generation) || ready.load(Ordering::SeqCst) {
+                    return;
+                }
+                manager.advance_generation();
+                log_line("timeout waiting for CLI readiness");
+                let stop_error = manager.stop_tracked_child().err();
+                let message = stop_error.map_or_else(
+                    || "CLI did not start in time".to_string(),
+                    |err| format!("CLI did not start in time; cleanup failed: {err}"),
+                );
+                let mut status = manager.status.lock();
+                status.state = CliState::Error;
+                status.error = Some(message.clone());
+                let snapshot = status.clone();
+                drop(status);
+                let _ = app.emit("cli:error", json!({"message": message}));
+                let _ = app.emit("cli:status", snapshot);
+            });
+        }
+
+        thread::spawn(move || loop {
+            enum Poll {
+                Running,
+                Exited(std::process::ExitStatus),
+                Failed(String),
+            }
+            let poll = {
+                let _lifecycle = manager.lifecycle.lock();
+                if !manager.is_current_generation(generation) {
+                    return;
+                }
+                let mut child = manager.child.lock();
+                let Some(tracked) = child.as_mut() else {
+                    return;
+                };
+                match tracked.try_wait() {
+                    Ok(Some(status)) => {
+                        #[cfg(unix)]
+                        let group_is_gone = process_group_is_gone(pid).map_err(|err| {
+                            format!("failed to inspect exited CLI pid={pid}: {err}")
+                        });
+                        #[cfg(windows)]
+                        let group_is_gone = match manager.job.lock().as_ref() {
+                            Some(job) => job.active_processes().map(|active| active == 0),
+                            None => Ok(false),
+                        };
+                        #[cfg(not(any(unix, windows)))]
+                        let group_is_gone: anyhow::Result<bool> = Ok(true);
+                        match group_is_gone {
+                            Ok(gone) if containment_is_complete(true, gone) => {
+                                *child = None;
+                                #[cfg(windows)]
+                                {
+                                    manager.job.lock().take();
+                                }
+                                Poll::Exited(status)
+                            }
+                            // The root may be only a launcher/wrapper. Keep ownership and
+                            // monitoring until the process group/job is actually empty.
+                            Ok(_) => Poll::Running,
+                            Err(err) => Poll::Failed(format!(
+                                "failed to inspect exited CLI pid={pid}: {err}"
+                            )),
+                        }
+                    }
+                    Ok(None) => Poll::Running,
+                    Err(err) => Poll::Failed(format!("failed to inspect CLI pid={pid}: {err}")),
+                }
+            };
+            match poll {
+                Poll::Running => thread::sleep(Duration::from_millis(100)),
+                Poll::Failed(message) => {
+                    manager.publish_error(&app, generation, message);
+                    return;
+                }
+                Poll::Exited(code) => {
+                    manager.with_current_generation(generation, || {
+                        let mut status = manager.status.lock();
+                        if status.state != CliState::Ready {
+                            status.state = CliState::Error;
+                            if status.error.is_none() {
+                                status.error = Some(format!("CLI exited early: {code}"));
+                            }
+                            let _ = app.emit(
+                                "cli:error",
+                                json!({"message": status.error.clone().unwrap_or_default()}),
+                            );
+                        } else {
+                            status.state = CliState::Stopped;
+                        }
+                        Self::emit_status(&app, &status);
+                    });
+                    return;
+                }
+            }
         });
 
         Ok(())
@@ -965,11 +1193,10 @@ impl CliProcessManager {
     fn process_stream<R: BufRead>(
         mut reader: R,
         stream: &str,
+        manager: &CliProcessManager,
+        generation: u64,
         app: &AppHandle,
-        status: &Arc<Mutex<CliStatus>>,
         ready: &Arc<AtomicBool>,
-        bootstrap_token: &Arc<Mutex<Option<String>>>,
-        session_cookie: &Arc<Mutex<Option<String>>>,
         auth_cookie_name: &str,
     ) {
         let mut buffer = String::new();
@@ -982,15 +1209,20 @@ impl CliProcessManager {
             match reader.read_line(&mut buffer) {
                 Ok(0) => break,
                 Ok(_) => {
+                    if !manager.is_current_generation(generation) {
+                        break;
+                    }
                     let line = buffer.trim_end();
                     if !line.is_empty() {
                         if line.starts_with(token_prefix) {
                             let token = line.trim_start_matches(token_prefix).trim();
                             if !token.is_empty() {
-                                let mut guard = bootstrap_token.lock();
-                                if guard.is_none() {
-                                    *guard = Some(token.to_string());
-                                }
+                                manager.with_current_generation(generation, || {
+                                    let mut guard = manager.bootstrap_token.lock();
+                                    if guard.is_none() {
+                                        *guard = Some(token.to_string());
+                                    }
+                                });
                             }
                             continue;
                         }
@@ -1002,13 +1234,15 @@ impl CliProcessManager {
                         }
 
                         if let Some(node_binary) = line.strip_prefix(MISSING_NODE_PREFIX) {
-                            let mut locked = status.lock();
-                            if locked.error.is_none() {
-                                locked.error = Some(format!(
-                                    "Node binary '{}' not found in the desktop shell environment. CodeNomad desktop currently requires Node.js installed on the system, or set NODE_BINARY to a valid runtime path.",
-                                    node_binary.trim()
-                                ));
-                            }
+                            manager.with_current_generation(generation, || {
+                                let mut locked = manager.status.lock();
+                                if locked.error.is_none() {
+                                    locked.error = Some(format!(
+                                        "Node binary '{}' not found in the desktop shell environment. CodeNomad desktop currently requires Node.js installed on the system, or set NODE_BINARY to a valid runtime path.",
+                                        node_binary.trim()
+                                    ));
+                                }
+                            });
                             continue;
                         }
 
@@ -1018,11 +1252,10 @@ impl CliProcessManager {
                             .map(|m| m.as_str().to_string())
                         {
                             Self::mark_ready(
+                                manager,
+                                generation,
                                 app,
-                                status,
                                 ready,
-                                bootstrap_token,
-                                session_cookie,
                                 auth_cookie_name,
                                 url,
                             );
@@ -1036,62 +1269,78 @@ impl CliProcessManager {
     }
 
     fn mark_ready(
+        manager: &CliProcessManager,
+        generation: u64,
         app: &AppHandle,
-        status: &Arc<Mutex<CliStatus>>,
         ready: &Arc<AtomicBool>,
-        bootstrap_token: &Arc<Mutex<Option<String>>>,
-        session_cookie: &Arc<Mutex<Option<String>>>,
         auth_cookie_name: &str,
         base_url: String,
     ) {
-        ready.store(true, Ordering::SeqCst);
+        if ready.swap(true, Ordering::SeqCst) {
+            return;
+        }
         let port = Url::parse(&base_url)
             .ok()
             .and_then(|u| u.port_or_known_default())
             .map(|p| p as u16);
-        let mut locked = status.lock();
-        locked.port = port;
-        locked.url = Some(base_url.clone());
-        locked.state = CliState::Ready;
-        locked.error = None;
+        let token = manager
+            .with_current_generation(generation, || {
+                let mut locked = manager.status.lock();
+                locked.port = port;
+                locked.url = Some(base_url.clone());
+                locked.state = CliState::Ready;
+                locked.error = None;
+                manager.bootstrap_token.lock().take()
+            })
+            .flatten();
+        if !manager.is_current_generation(generation) {
+            return;
+        }
         log_line(&format!("cli ready on {base_url}"));
 
-        let token = bootstrap_token.lock().take();
-
         if let Some(token) = token {
             // Token exchange is only implemented for loopback HTTP. If localUrl is HTTPS,
             // skip the exchange and let the user authenticate normally.
             let scheme = Url::parse(&base_url).ok().map(|u| u.scheme().to_string());
             if scheme.as_deref() != Some("http") {
-                navigate_main(app, &base_url);
+                navigate_main(manager, generation, app, &base_url);
             } else {
                 match exchange_bootstrap_token(&base_url, &token, &auth_cookie_name) {
                     Ok(Some(session_id)) => {
-                        if let Err(err) =
+                        let cookie_result = manager.with_current_generation(generation, || {
                             set_session_cookie(app, &base_url, &auth_cookie_name, &session_id)
-                        {
+                        });
+                        if cookie_result.is_none() {
+                            return;
+                        }
+                        if let Err(err) = cookie_result.unwrap() {
                             log_line(&format!("failed to set session cookie: {err}"));
-                            navigate_main(app, &format!("{base_url}/login"));
+                            navigate_main(manager, generation, app, &format!("{base_url}/login"));
                         } else {
-                            *session_cookie.lock() = Some(session_id.clone());
-                            navigate_main(app, &base_url);
+                            manager.with_current_generation(generation, || {
+                                *manager.session_cookie.lock() = Some(session_id.clone());
+                            });
+                            navigate_main(manager, generation, app, &base_url);
                         }
                     }
                     Ok(None) => {
                         log_line("bootstrap token exchange failed (invalid token)");
-                        navigate_main(app, &format!("{base_url}/login"));
+                        navigate_main(manager, generation, app, &format!("{base_url}/login"));
                     }
                     Err(err) => {
                         log_line(&format!("bootstrap token exchange failed: {err}"));
-                        navigate_main(app, &format!("{base_url}/login"));
+                        navigate_main(manager, generation, app, &format!("{base_url}/login"));
                     }
                 }
             }
         } else {
-            navigate_main(app, &base_url);
+            navigate_main(manager, generation, app, &base_url);
         }
-        let _ = app.emit("cli:ready", locked.clone());
-        Self::emit_status(app, &locked);
+        manager.with_current_generation(generation, || {
+            let status = manager.status.lock().clone();
+            let _ = app.emit("cli:ready", status.clone());
+            Self::emit_status(app, &status);
+        });
     }
 
     fn emit_status(app: &AppHandle, status: &CliStatus) {
@@ -1489,4 +1738,140 @@ mod tests {
         std::env::remove_var("CODENOMAD_UI_LAUNCH_QUERY");
         assert_eq!(augmented, "http://127.0.0.1:3000?existing=true&debug=true");
     }
+
+    #[test]
+    fn stale_generation_cannot_publish_status() {
+        let manager = CliProcessManager::new();
+        let first = manager.advance_generation();
+        manager.with_current_generation(first, || {
+            manager.status.lock().state = CliState::Starting;
+        });
+        let second = manager.advance_generation();
+
+        assert!(manager
+            .with_current_generation(first, || {
+                manager.status.lock().state = CliState::Ready;
+            })
+            .is_none());
+        assert_eq!(manager.status().state, CliState::Starting);
+        assert!(manager
+            .with_current_generation(second, || {
+                manager.status.lock().state = CliState::Ready;
+            })
+            .is_some());
+        assert_eq!(manager.status().state, CliState::Ready);
+    }
+
+    #[test]
+    fn stop_waits_for_an_authorized_spawn_section() {
+        let manager = CliProcessManager::new();
+        let generation = manager.advance_generation();
+        let worker_manager = manager.clone();
+        let (authorized_tx, authorized_rx) = std::sync::mpsc::channel();
+        let (release_tx, release_rx) = std::sync::mpsc::channel();
+        let worker = std::thread::spawn(move || {
+            let _lifecycle = worker_manager.lock_current_generation(generation).unwrap();
+            authorized_tx.send(()).unwrap();
+            release_rx.recv().unwrap();
+        });
+        authorized_rx.recv().unwrap();
+
+        let stopping_manager = manager.clone();
+        let (stopped_tx, stopped_rx) = std::sync::mpsc::channel();
+        let stopping = std::thread::spawn(move || {
+            stopping_manager.stop().unwrap();
+            stopped_tx.send(()).unwrap();
+        });
+        assert!(stopped_rx.recv_timeout(Duration::from_millis(20)).is_err());
+
+        release_tx.send(()).unwrap();
+        worker.join().unwrap();
+        stopped_rx.recv_timeout(Duration::from_secs(1)).unwrap();
+        stopping.join().unwrap();
+        assert!(!manager.is_current_generation(generation));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_launch_gate_requires_parent_release() {
+        assert!(!wait_for_windows_cli_launch_gate(std::io::Cursor::new([])));
+        assert!(!wait_for_windows_cli_launch_gate(std::io::Cursor::new([0])));
+        assert!(wait_for_windows_cli_launch_gate(std::io::Cursor::new([1])));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_launcher_preserves_the_shutdown_control_channel() {
+        let mut control = std::io::Cursor::new(b"\x01codenomad:shutdown\n");
+        let mut node_stdin = Vec::new();
+
+        assert!(wait_for_windows_cli_launch_gate(&mut control));
+        relay_windows_cli_control(&mut control, &mut node_stdin).unwrap();
+
+        assert_eq!(node_stdin, b"codenomad:shutdown\n");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_stop_writes_the_exact_shutdown_command() {
+        let mut control = Vec::new();
+        request_windows_cli_shutdown(&mut control).unwrap();
+        assert_eq!(control, b"codenomad:shutdown\n");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_requires_an_empty_job_to_confirm_containment() {
+        assert!(windows_containment_confirmed(true, Some(0)));
+        assert!(!windows_containment_confirmed(true, Some(1)));
+        assert!(!windows_containment_confirmed(true, None));
+        assert!(!windows_containment_confirmed(false, Some(0)));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_exited_child_without_job_remains_unconfirmed() {
+        let mut command = Command::new("cmd.exe");
+        command.args(["/C", "exit", "0"]);
+        configure_spawn(&mut command);
+        let mut child = command.spawn().unwrap();
+        child.wait().unwrap();
+
+        let error = stop_child(&mut child, None).unwrap_err().to_string();
+        assert!(error.contains("cannot be confirmed without a Windows job"));
+    }
+
+    #[test]
+    fn exited_root_is_not_complete_while_descendants_remain() {
+        assert!(!containment_is_complete(true, false));
+        assert!(containment_is_complete(true, true));
+    }
+
+    #[test]
+    fn termination_wait_propagates_probe_errors() {
+        let result = wait_for_termination(Duration::ZERO, Duration::ZERO, || {
+            Err(anyhow::anyhow!("try_wait failed"))
+        });
+        assert_eq!(result.unwrap_err().to_string(), "try_wait failed");
+    }
+
+    #[test]
+    fn termination_wait_rejects_unconfirmed_exit() {
+        let result = wait_for_termination(Duration::ZERO, Duration::ZERO, || Ok(false));
+        assert_eq!(
+            result.unwrap_err().to_string(),
+            "process termination was not confirmed"
+        );
+    }
+
+    #[test]
+    fn termination_wait_accepts_confirmed_exit() {
+        let mut probes = 0;
+        wait_for_termination(Duration::from_secs(1), Duration::ZERO, || {
+            probes += 1;
+            Ok(probes == 2)
+        })
+        .unwrap();
+        assert_eq!(probes, 2);
+    }
 }
diff --git a/packages/tauri-app/src-tauri/src/client_state.rs b/packages/tauri-app/src-tauri/src/client_state.rs
new file mode 100644
index 00000000..d2b37b18
--- /dev/null
+++ b/packages/tauri-app/src-tauri/src/client_state.rs
@@ -0,0 +1,683 @@
+mod access;
+mod commands;
+mod cross_host;
+mod navigation;
+mod process;
+mod window;
+
+#[doc(hidden)]
+pub use commands::{
+    __cmd__client_state_claim_access, __cmd__client_state_clear, __cmd__client_state_load,
+    __cmd__client_state_navigation_flushed, __cmd__client_state_renderer_flushed,
+    __cmd__client_state_save, __cmd__client_state_set_restore_enabled,
+};
+pub use commands::{
+    client_state_claim_access, client_state_clear, client_state_load,
+    client_state_navigation_flushed, client_state_renderer_flushed, client_state_save,
+    client_state_set_restore_enabled,
+};
+pub(crate) use navigation::{
+    before_main_window_navigation, before_main_window_navigation_if, NavigationKind,
+};
+pub use window::{
+    capture_and_flush_main_window, main_window_zoom, set_main_window_zoom, setup_main_window,
+    DEFAULT_ZOOM_LEVEL,
+};
+
+use serde::Serialize;
+use serde_json::Value;
+use std::fs;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
+use tauri::{AppHandle, Emitter, Manager};
+use url::Url;
+use window::NativeWindowState;
+
+const CLIENT_STATE_VERSION: u64 = 1;
+const CLIENT_STATE_FILENAME: &str = "client-state.json";
+const MAX_CLIENT_SNAPSHOT_BYTES: usize = 1024 * 1024;
+const RENDERER_FLUSH_TIMEOUT: Duration = Duration::from_secs(1);
+
+#[derive(Clone, Copy, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct RendererFlushRequest {
+    pub(crate) generation: u64,
+}
+
+#[derive(Default)]
+struct RendererFlush {
+    request_lock: Mutex<()>,
+    next_generation: AtomicU64,
+    acknowledged_generation: AtomicU64,
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct PersistedClientState {
+    version: u64,
+    restore_enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    snapshot: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    window: Option<NativeWindowState>,
+    #[serde(skip)]
+    unsupported_future_envelope: bool,
+    #[serde(skip)]
+    writes_enabled: bool,
+}
+
+impl Default for PersistedClientState {
+    fn default() -> Self {
+        Self {
+            version: CLIENT_STATE_VERSION,
+            restore_enabled: true,
+            snapshot: None,
+            window: None,
+            unsupported_future_envelope: false,
+            writes_enabled: true,
+        }
+    }
+}
+
+#[derive(Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ClientStateLoadResult {
+    is_primary: bool,
+    restore_enabled: bool,
+    snapshot: Value,
+}
+
+pub struct ClientState {
+    state_path: PathBuf,
+    process: process::ProcessState,
+    state: Mutex<PersistedClientState>,
+    zoom_level: Mutex<f64>,
+    write_lock: Mutex<()>,
+    save_generation: AtomicU64,
+    renderer_access: access::RendererAccess,
+    renderer_flush: RendererFlush,
+    write_state: StateWriter,
+}
+
+type StateWriter =
+    std::sync::Arc<dyn Fn(&Path, &[u8], &dyn Fn() -> bool) -> Result<(), String> + Send + Sync>;
+
+impl ClientState {
+    pub fn initialize(app: &AppHandle) -> Self {
+        match app.path().app_data_dir() {
+            Ok(app_data_dir) => {
+                match (cross_host::election_directory(), cross_host::state_path()) {
+                    (Ok(election_dir), Ok(state_path)) => {
+                        let legacy_electron = cross_host::legacy_electron_data_directory();
+                        Self::initialize_managed_at_with_election(
+                            &app_data_dir,
+                            &election_dir,
+                            &state_path,
+                            legacy_electron.as_deref(),
+                        )
+                    }
+                    (Err(err), _) | (_, Err(err)) => {
+                        eprintln!("[client-state] initialization failed; restore disabled: {err}");
+                        Self::disabled(app_data_dir.join(CLIENT_STATE_FILENAME))
+                    }
+                }
+            }
+            Err(err) => {
+                eprintln!("[client-state] initialization failed; restore disabled: {err}");
+                Self::disabled(PathBuf::new())
+            }
+        }
+    }
+
+    #[cfg(test)]
+    fn initialize_managed_at(app_data_dir: &Path) -> Self {
+        Self::initialize_at(app_data_dir).unwrap_or_else(|err| {
+            eprintln!("[client-state] initialization failed; restore disabled: {err}");
+            Self::disabled(app_data_dir.join(CLIENT_STATE_FILENAME))
+        })
+    }
+
+    fn initialize_managed_at_with_election(
+        app_data_dir: &Path,
+        election_dir: &Path,
+        state_path: &Path,
+        legacy_electron_data_dir: Option<&Path>,
+    ) -> Self {
+        Self::initialize_at_with_writer_and_election(
+            app_data_dir,
+            election_dir,
+            state_path,
+            legacy_electron_data_dir,
+            std::sync::Arc::new(write_atomically),
+        )
+        .unwrap_or_else(|err| {
+            eprintln!("[client-state] initialization failed; restore disabled: {err}");
+            Self::disabled(app_data_dir.join(CLIENT_STATE_FILENAME))
+        })
+    }
+
+    fn disabled(state_path: PathBuf) -> Self {
+        let state = PersistedClientState {
+            restore_enabled: false,
+            writes_enabled: false,
+            ..PersistedClientState::default()
+        };
+        Self::new(
+            state_path,
+            process::ProcessState::disabled(),
+            state,
+            std::sync::Arc::new(write_atomically),
+        )
+    }
+
+    fn new(
+        state_path: PathBuf,
+        process: process::ProcessState,
+        state: PersistedClientState,
+        write_state: StateWriter,
+    ) -> Self {
+        let zoom_level = state
+            .restore_enabled
+            .then(|| state.window.as_ref().map(|window| window.zoom_factor))
+            .flatten()
+            .unwrap_or(DEFAULT_ZOOM_LEVEL);
+        Self {
+            state_path,
+            process,
+            state: Mutex::new(state),
+            zoom_level: Mutex::new(zoom_level),
+            write_lock: Mutex::new(()),
+            save_generation: AtomicU64::new(0),
+            renderer_access: access::RendererAccess::default(),
+            renderer_flush: RendererFlush::default(),
+            write_state,
+        }
+    }
+
+    #[cfg(test)]
+    fn initialize_at(app_data_dir: &Path) -> Result<Self, String> {
+        Self::initialize_at_with_writer(app_data_dir, std::sync::Arc::new(write_atomically))
+    }
+
+    #[cfg(test)]
+    fn initialize_at_with_writer(
+        app_data_dir: &Path,
+        write_state: StateWriter,
+    ) -> Result<Self, String> {
+        Self::initialize_at_with_writer_and_election(
+            app_data_dir,
+            &app_data_dir.join(".cross-host-election"),
+            &app_data_dir.join(CLIENT_STATE_FILENAME),
+            None,
+            write_state,
+        )
+    }
+
+    fn initialize_at_with_writer_and_election(
+        app_data_dir: &Path,
+        election_dir: &Path,
+        state_path: &Path,
+        legacy_electron_data_dir: Option<&Path>,
+        write_state: StateWriter,
+    ) -> Result<Self, String> {
+        fs::create_dir_all(app_data_dir).map_err(|err| {
+            format!(
+                "failed to create app data directory {}: {err}",
+                app_data_dir.display()
+            )
+        })?;
+
+        let registration = process::Registration::initialize(
+            app_data_dir,
+            election_dir,
+            legacy_electron_data_dir,
+        )?;
+        let future_legacy =
+            !state_path.exists() && has_future_legacy_state(app_data_dir, legacy_electron_data_dir);
+        if registration.is_primary() && !state_path.exists() && !future_legacy {
+            migrate_legacy_state(state_path, app_data_dir, legacy_electron_data_dir, &|| {
+                registration.is_primary()
+            })?;
+        }
+        let state = if registration.is_primary() {
+            if future_legacy {
+                PersistedClientState {
+                    restore_enabled: false,
+                    unsupported_future_envelope: true,
+                    writes_enabled: false,
+                    ..PersistedClientState::default()
+                }
+            } else {
+                read_client_state(state_path)
+            }
+        } else {
+            PersistedClientState::default()
+        };
+        let process = registration.finish();
+        Ok(Self::new(
+            state_path.to_path_buf(),
+            process,
+            state,
+            write_state,
+        ))
+    }
+
+    fn is_primary(&self) -> bool {
+        self.process.is_primary()
+    }
+
+    fn claim_renderer_access(&self, access_token: &str, renderer_url: &Url) -> Result<(), String> {
+        let _write = self.write_lock.lock().map_err(|err| err.to_string())?;
+        self.renderer_access.claim(access_token, renderer_url)
+    }
+
+    fn load(&self) -> Result<ClientStateLoadResult, String> {
+        let state = self.state.lock().map_err(|err| err.to_string())?;
+        let is_primary = self.is_primary();
+        Ok(ClientStateLoadResult {
+            is_primary,
+            restore_enabled: if is_primary || !self.process.is_registered() {
+                state.restore_enabled
+            } else {
+                true
+            },
+            snapshot: if is_primary && state.restore_enabled {
+                state.snapshot.clone().unwrap_or(Value::Null)
+            } else {
+                Value::Null
+            },
+        })
+    }
+
+    #[cfg(test)]
+    fn save_snapshot(&self, snapshot: Value) -> Result<bool, String> {
+        self.save_snapshot_guarded(snapshot, || true)
+    }
+
+    fn save_snapshot_guarded(
+        &self,
+        snapshot: Value,
+        access_valid: impl Fn() -> bool,
+    ) -> Result<bool, String> {
+        let _write = self.write_lock.lock().map_err(|err| err.to_string())?;
+        if !access_valid() {
+            return Err("Client state renderer authority changed before mutation".to_string());
+        }
+        if !self.is_primary() {
+            return Ok(false);
+        }
+        if self.normal_writes_suppressed()? {
+            return Ok(true);
+        }
+        if serialized_value_size(&snapshot)? > MAX_CLIENT_SNAPSHOT_BYTES {
+            return Err("Client snapshot exceeds the 1 MiB limit".to_string());
+        }
+
+        self.mutate_and_write(|state| state.snapshot = Some(snapshot), &access_valid)
+    }
+
+    #[cfg(test)]
+    fn set_restore_enabled(&self, enabled: bool) -> Result<bool, String> {
+        self.set_restore_enabled_guarded(enabled, || true)
+    }
+
+    fn set_restore_enabled_guarded(
+        &self,
+        enabled: bool,
+        access_valid: impl Fn() -> bool,
+    ) -> Result<bool, String> {
+        let _write = self.write_lock.lock().map_err(|err| err.to_string())?;
+        if !access_valid() {
+            return Err("Client state renderer authority changed before mutation".to_string());
+        }
+        if !self.is_primary() {
+            return Ok(false);
+        }
+        if self
+            .state
+            .lock()
+            .map_err(|err| err.to_string())?
+            .unsupported_future_envelope
+        {
+            return Ok(false);
+        }
+        self.mutate_and_write(
+            |state| {
+                state.restore_enabled = enabled;
+                if !enabled {
+                    state.snapshot = None;
+                    state.window = None;
+                }
+                state.writes_enabled = enabled;
+            },
+            &access_valid,
+        )
+    }
+
+    #[cfg(test)]
+    fn clear(&self) -> Result<bool, String> {
+        self.clear_guarded(|| true)
+    }
+
+    fn clear_guarded(&self, access_valid: impl Fn() -> bool) -> Result<bool, String> {
+        let _write = self.write_lock.lock().map_err(|err| err.to_string())?;
+        if !access_valid() {
+            return Err("Client state renderer authority changed before mutation".to_string());
+        }
+        if !self.is_primary() {
+            return Ok(false);
+        }
+        self.mutate_and_write(
+            |state| {
+                if state.unsupported_future_envelope {
+                    *state = PersistedClientState::default();
+                } else {
+                    state.snapshot = None;
+                    state.window = None;
+                    state.writes_enabled = false;
+                }
+            },
+            &access_valid,
+        )
+    }
+
+    fn flush(&self) -> Result<(), String> {
+        let _write = self.write_lock.lock().map_err(|err| err.to_string())?;
+        if self.is_primary() && !self.normal_writes_suppressed()? {
+            self.write_current_state()?;
+        }
+        Ok(())
+    }
+
+    fn normal_writes_suppressed(&self) -> Result<bool, String> {
+        self.state
+            .lock()
+            .map(|state| !state.writes_enabled || state.unsupported_future_envelope)
+            .map_err(|err| err.to_string())
+    }
+
+    fn write_current_state(&self) -> Result<(), String> {
+        self.write_current_state_guarded(&|| true)
+    }
+
+    fn write_current_state_guarded(
+        &self,
+        replacement_valid: &dyn Fn() -> bool,
+    ) -> Result<(), String> {
+        let bytes = {
+            let state = self.state.lock().map_err(|err| err.to_string())?;
+            serde_json::to_vec(&*state).map_err(|err| err.to_string())?
+        };
+        (self.write_state)(&self.state_path, &bytes, &|| {
+            self.is_primary() && replacement_valid()
+        })?;
+        Ok(())
+    }
+
+    fn mutate_and_write(
+        &self,
+        mutate: impl FnOnce(&mut PersistedClientState),
+        replacement_valid: &dyn Fn() -> bool,
+    ) -> Result<bool, String> {
+        let previous_state = {
+            let mut state = self.state.lock().map_err(|err| err.to_string())?;
+            let previous = state.clone();
+            mutate(&mut state);
+            previous
+        };
+
+        match self.write_current_state_guarded(replacement_valid) {
+            Ok(()) => Ok(true),
+            Err(err) => {
+                *self.state.lock().map_err(|lock_err| lock_err.to_string())? = previous_state;
+                Err(err)
+            }
+        }
+    }
+
+    fn release_locks(&self) {
+        let _write = self
+            .write_lock
+            .lock()
+            .unwrap_or_else(|err| err.into_inner());
+        self.process.release_locks();
+    }
+
+    pub(crate) fn wait_for_renderer_flush(&self, app: &AppHandle, require_claim: bool) {
+        let _request = self
+            .renderer_flush
+            .request_lock
+            .lock()
+            .unwrap_or_else(|err| err.into_inner());
+        if require_claim && !self.renderer_access.is_claimed() {
+            return;
+        }
+        let Some(window) = app.get_webview_window("main") else {
+            return;
+        };
+        let generation = self
+            .renderer_flush
+            .next_generation
+            .fetch_add(1, Ordering::SeqCst)
+            + 1;
+        if let Err(err) = window.emit(
+            "client-state:navigation-flush-requested",
+            RendererFlushRequest { generation },
+        ) {
+            eprintln!("[client-state] failed to request renderer flush: {err}");
+            return;
+        }
+
+        let deadline = Instant::now() + RENDERER_FLUSH_TIMEOUT;
+        while self.renderer_flush.next_generation.load(Ordering::SeqCst) == generation
+            && self
+                .renderer_flush
+                .acknowledged_generation
+                .load(Ordering::SeqCst)
+                != generation
+            && Instant::now() < deadline
+        {
+            std::thread::sleep(Duration::from_millis(10));
+        }
+    }
+
+    fn acknowledge_renderer_flush(&self, generation: u64) {
+        if self.renderer_flush.next_generation.load(Ordering::SeqCst) == generation {
+            self.renderer_flush
+                .acknowledged_generation
+                .store(generation, Ordering::SeqCst);
+        }
+    }
+}
+
+impl Drop for ClientState {
+    fn drop(&mut self) {
+        self.release_locks();
+    }
+}
+
+fn read_client_state(path: &Path) -> PersistedClientState {
+    match fs::read(path) {
+        Ok(bytes) => parse_client_state(&bytes),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => PersistedClientState::default(),
+        Err(err) => {
+            eprintln!("[client-state] failed to read state: {err}");
+            PersistedClientState::default()
+        }
+    }
+}
+
+fn parse_client_state(bytes: &[u8]) -> PersistedClientState {
+    let Ok(Value::Object(value)) = serde_json::from_slice::<Value>(bytes) else {
+        return PersistedClientState::default();
+    };
+    let version = value.get("version").and_then(Value::as_u64);
+    if version.is_some_and(|version| version > CLIENT_STATE_VERSION) {
+        return PersistedClientState {
+            restore_enabled: false,
+            unsupported_future_envelope: true,
+            writes_enabled: false,
+            ..PersistedClientState::default()
+        };
+    }
+    if version != Some(CLIENT_STATE_VERSION) {
+        return PersistedClientState::default();
+    }
+
+    let snapshot = value.get("snapshot").cloned().filter(|snapshot| {
+        serialized_value_size(snapshot)
+            .map(|size| size <= MAX_CLIENT_SNAPSHOT_BYTES)
+            .unwrap_or(false)
+    });
+    let restore_enabled = value
+        .get("restoreEnabled")
+        .and_then(Value::as_bool)
+        .unwrap_or(true);
+    PersistedClientState {
+        version: CLIENT_STATE_VERSION,
+        restore_enabled,
+        snapshot,
+        window: value.get("window").and_then(window::normalize_window_state),
+        unsupported_future_envelope: false,
+        writes_enabled: restore_enabled,
+    }
+}
+
+fn legacy_candidate(
+    path: &Path,
+    host: &'static str,
+) -> Option<(PersistedClientState, bool, i64, &'static str)> {
+    let bytes = fs::read(path).ok()?;
+    let Value::Object(value) = serde_json::from_slice::<Value>(&bytes).ok()? else {
+        return None;
+    };
+    if value.get("version").and_then(Value::as_u64) != Some(CLIENT_STATE_VERSION) {
+        return None;
+    }
+    let saved_at = value
+        .get("snapshot")
+        .and_then(Value::as_object)
+        .and_then(|snapshot| snapshot.get("savedAt"))
+        .and_then(Value::as_i64)
+        .unwrap_or(-1);
+    let mut parsed = parse_client_state(&bytes);
+    parsed.window = None;
+    Some((parsed, value.contains_key("snapshot"), saved_at, host))
+}
+
+fn has_future_legacy_state(tauri_data_dir: &Path, electron_data_dir: Option<&Path>) -> bool {
+    [
+        electron_data_dir.map(|path| path.join(CLIENT_STATE_FILENAME)),
+        Some(tauri_data_dir.join(CLIENT_STATE_FILENAME)),
+    ]
+    .into_iter()
+    .flatten()
+    .any(|path| {
+        fs::read(path)
+            .ok()
+            .and_then(|bytes| serde_json::from_slice::<Value>(&bytes).ok())
+            .and_then(|value| value.get("version").and_then(Value::as_u64))
+            .is_some_and(|version| version > CLIENT_STATE_VERSION)
+    })
+}
+
+fn migrate_legacy_state(
+    state_path: &Path,
+    tauri_data_dir: &Path,
+    electron_data_dir: Option<&Path>,
+    ownership_valid: &dyn Fn() -> bool,
+) -> Result<(), String> {
+    let mut candidates = [
+        electron_data_dir
+            .and_then(|path| legacy_candidate(&path.join(CLIENT_STATE_FILENAME), "electron")),
+        legacy_candidate(&tauri_data_dir.join(CLIENT_STATE_FILENAME), "tauri"),
+    ]
+    .into_iter()
+    .flatten()
+    .collect::<Vec<_>>();
+    candidates.sort_by(|left, right| {
+        left.0
+            .restore_enabled
+            .cmp(&right.0.restore_enabled)
+            .then_with(|| left.1.cmp(&right.1))
+            .then_with(|| right.2.cmp(&left.2))
+            .then_with(|| right.3.cmp(left.3))
+    });
+    let Some((state, _, _, _)) = candidates.first() else {
+        return Ok(());
+    };
+    let bytes = serde_json::to_vec(state).map_err(|err| err.to_string())?;
+    if let Some(parent) = state_path.parent() {
+        fs::create_dir_all(parent)
+            .map_err(|err| format!("failed to create shared client-state directory: {err}"))?;
+    }
+    write_atomically(state_path, &bytes, ownership_valid)?;
+    for path in [
+        electron_data_dir.map(|path| path.join(CLIENT_STATE_FILENAME)),
+        Some(tauri_data_dir.join(CLIENT_STATE_FILENAME)),
+    ]
+    .into_iter()
+    .flatten()
+    {
+        match fs::remove_file(path) {
+            Ok(()) => {}
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+            Err(err) => {
+                return Err(format!(
+                    "failed to remove migrated legacy client state: {err}"
+                ))
+            }
+        }
+    }
+    Ok(())
+}
+
+fn serialized_value_size(value: &Value) -> Result<usize, String> {
+    serde_json::to_vec(value)
+        .map(|bytes| bytes.len())
+        .map_err(|err| err.to_string())
+}
+
+fn write_atomically(
+    path: &Path,
+    bytes: &[u8],
+    ownership_valid: &dyn Fn() -> bool,
+) -> Result<(), String> {
+    let parent = path
+        .parent()
+        .ok_or_else(|| format!("state path has no parent: {}", path.display()))?;
+    let mut temporary = tempfile::NamedTempFile::new_in(parent)
+        .map_err(|err| format!("failed to create temporary state file: {err}"))?;
+    temporary
+        .write_all(bytes)
+        .and_then(|_| temporary.as_file().sync_all())
+        .map_err(|err| format!("failed to write temporary state file: {err}"))?;
+    if !ownership_valid() {
+        return Err("Client state ownership changed before atomic replacement".to_string());
+    }
+    temporary
+        .persist(path)
+        .map_err(|err| format!("failed to replace state file: {}", err.error))?;
+    Ok(())
+}
+
+pub fn release(app: &AppHandle) {
+    if let Some(state) = app.try_state::<ClientState>() {
+        state.release_locks();
+    }
+}
+
+pub fn flush_and_release_without_window_capture(app: &AppHandle) {
+    if let Some(state) = app.try_state::<ClientState>() {
+        if let Err(err) = state.flush() {
+            eprintln!("[client-state] failed to flush state: {err}");
+        }
+        state.release_locks();
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/packages/tauri-app/src-tauri/src/client_state/access.rs b/packages/tauri-app/src-tauri/src/client_state/access.rs
new file mode 100644
index 00000000..31181c62
--- /dev/null
+++ b/packages/tauri-app/src-tauri/src/client_state/access.rs
@@ -0,0 +1,130 @@
+use std::sync::Mutex;
+use url::Url;
+
+#[derive(Default)]
+pub(super) struct RendererAccess {
+    state: Mutex<RendererAccessState>,
+}
+
+#[derive(Default)]
+struct RendererAccessState {
+    token: Option<String>,
+    committed_origin: Option<String>,
+    pending_origin: Option<String>,
+    generation: u64,
+}
+
+pub(super) struct PendingNavigation {
+    previous_origin: Option<String>,
+    staged_origin: Option<String>,
+}
+
+fn origin_key(url: &Url) -> Result<String, String> {
+    match (url.scheme(), url.host_str()) {
+        ("http" | "https", Some(_)) => Ok(url.origin().ascii_serialization()),
+        ("tauri" | "asset", Some(host)) => Ok(format!("{}://{}", url.scheme(), host)),
+        _ => Err("Client state renderer URL does not have a supported origin".to_string()),
+    }
+}
+
+impl RendererAccess {
+    pub(super) fn claim(&self, access_token: &str, renderer_url: &Url) -> Result<(), String> {
+        if access_token.is_empty() {
+            return Err("Client state access token must not be empty".to_string());
+        }
+
+        let renderer_origin = origin_key(renderer_url)?;
+        let mut state = self.state.lock().map_err(|err| err.to_string())?;
+        if state.token.is_none()
+            || state.pending_origin.as_deref() == Some(renderer_origin.as_str())
+        {
+            state.token = Some(access_token.to_string());
+            state.committed_origin = Some(renderer_origin);
+            state.pending_origin = None;
+            state.generation = state.generation.wrapping_add(1);
+            return Ok(());
+        }
+        if state.token.as_deref() != Some(access_token) {
+            return Err("Client state access token does not match this renderer".to_string());
+        }
+        if state.committed_origin.as_deref() == Some(renderer_origin.as_str()) {
+            Ok(())
+        } else {
+            Err("Client state renderer origin changed without access rotation".to_string())
+        }
+    }
+
+    pub(super) fn validate(&self, access_token: &str, renderer_url: &Url) -> Result<u64, String> {
+        if access_token.is_empty() {
+            return Err("Client state access token must not be empty".to_string());
+        }
+
+        let renderer_origin = origin_key(renderer_url)?;
+        let state = self.state.lock().map_err(|err| err.to_string())?;
+        if state.token.as_deref() == Some(access_token)
+            && state.committed_origin.as_deref() == Some(renderer_origin.as_str())
+        {
+            return Ok(state.generation);
+        }
+        match state.token.as_deref() {
+            Some(current) if current == access_token => {
+                Err("Client state renderer origin does not match this renderer".to_string())
+            }
+            Some(_) => Err("Client state access token does not match this renderer".to_string()),
+            None => Err("Client state access has not been claimed by this renderer".to_string()),
+        }
+    }
+
+    pub(super) fn is_generation_current(&self, generation: u64) -> bool {
+        self.state
+            .lock()
+            .map(|state| state.generation == generation)
+            .unwrap_or(false)
+    }
+
+    pub(super) fn allows_claim_origin(&self, renderer_url: &Url) -> bool {
+        let Ok(renderer_origin) = origin_key(renderer_url) else {
+            return false;
+        };
+        self.state
+            .lock()
+            .map(|state| {
+                state.committed_origin.as_deref() == Some(renderer_origin.as_str())
+                    || state.pending_origin.as_deref() == Some(renderer_origin.as_str())
+            })
+            .unwrap_or(false)
+    }
+
+    pub(super) fn begin_navigation(
+        &self,
+        target_url: Option<&Url>,
+    ) -> Result<PendingNavigation, String> {
+        let mut state = self.state.lock().map_err(|err| err.to_string())?;
+        let previous_origin = state.pending_origin.clone();
+        let staged_origin = match target_url {
+            Some(url) => Some(origin_key(url)?),
+            None => previous_origin
+                .clone()
+                .or_else(|| state.committed_origin.clone()),
+        };
+        state.pending_origin = staged_origin.clone();
+        Ok(PendingNavigation {
+            previous_origin,
+            staged_origin,
+        })
+    }
+
+    pub(super) fn cancel_navigation(&self, navigation: PendingNavigation) {
+        let mut state = self.state.lock().unwrap_or_else(|err| err.into_inner());
+        if state.pending_origin == navigation.staged_origin {
+            state.pending_origin = navigation.previous_origin;
+        }
+    }
+
+    pub(super) fn is_claimed(&self) -> bool {
+        self.state
+            .lock()
+            .map(|state| state.token.is_some())
+            .unwrap_or(false)
+    }
+}
diff --git a/packages/tauri-app/src-tauri/src/client_state/commands.rs b/packages/tauri-app/src-tauri/src/client_state/commands.rs
new file mode 100644
index 00000000..f22b6423
--- /dev/null
+++ b/packages/tauri-app/src-tauri/src/client_state/commands.rs
@@ -0,0 +1,153 @@
+use super::{ClientState, ClientStateLoadResult};
+use crate::AppState;
+use serde_json::Value;
+use tauri::{AppHandle, State, WebviewWindow};
+use url::Url;
+
+fn same_origin(url: &Url, expected: &str) -> bool {
+    Url::parse(expected)
+        .map(|expected| url.origin() == expected.origin())
+        .unwrap_or(false)
+}
+
+fn is_app_renderer_origin(url: &Url) -> bool {
+    match url.scheme() {
+        "tauri" | "asset" => url.host_str() == Some("localhost") && url.port().is_none(),
+        "http" | "https" => url.host_str() == Some("tauri.localhost") && url.port().is_none(),
+        _ => false,
+    }
+}
+
+fn is_dev_renderer_origin(url: &Url) -> bool {
+    cfg!(debug_assertions)
+        && url.scheme() == "http"
+        && matches!(url.host_str(), Some("127.0.0.1" | "localhost"))
+        && url.port() == Some(1420)
+}
+
+pub(super) fn is_allowed_client_state_origin(url: &Url, managed_cli_url: Option<&str>) -> bool {
+    managed_cli_url
+        .map(|expected| same_origin(url, expected))
+        .unwrap_or(false)
+        || is_app_renderer_origin(url)
+        || is_dev_renderer_origin(url)
+}
+
+fn main_window_url(window: &WebviewWindow) -> Result<Url, String> {
+    if window.label() != "main" {
+        return Err(
+            "Client state commands are only available to the local main window".to_string(),
+        );
+    }
+
+    window
+        .url()
+        .map_err(|err| format!("failed to inspect current renderer URL: {err}"))
+}
+
+fn validate_claim_origin(
+    current_url: &Url,
+    app_state: &AppState,
+    state: &ClientState,
+) -> Result<(), String> {
+    let status = app_state.manager.status();
+    if state.renderer_access.allows_claim_origin(current_url)
+        || is_allowed_client_state_origin(current_url, status.url.as_deref())
+    {
+        Ok(())
+    } else {
+        Err("Client state commands are not available to the current renderer origin".to_string())
+    }
+}
+
+fn validate_access(
+    window: &WebviewWindow,
+    state: &ClientState,
+    access_token: &str,
+) -> Result<u64, String> {
+    let current_url = main_window_url(window)?;
+    state.renderer_access.validate(access_token, &current_url)
+}
+
+#[tauri::command]
+pub fn client_state_claim_access(
+    window: WebviewWindow,
+    app_state: State<'_, AppState>,
+    state: State<'_, ClientState>,
+    access_token: String,
+) -> Result<(), String> {
+    let current_url = main_window_url(&window)?;
+    validate_claim_origin(&current_url, &app_state, &state)?;
+    state.claim_renderer_access(&access_token, &current_url)
+}
+
+#[tauri::command]
+pub fn client_state_load(
+    window: WebviewWindow,
+    state: State<'_, ClientState>,
+    access_token: String,
+) -> Result<ClientStateLoadResult, String> {
+    validate_access(&window, &state, &access_token)?;
+    state.load()
+}
+
+#[tauri::command]
+pub fn client_state_save(
+    window: WebviewWindow,
+    state: State<'_, ClientState>,
+    access_token: String,
+    snapshot: Value,
+) -> Result<bool, String> {
+    let generation = validate_access(&window, &state, &access_token)?;
+    state.save_snapshot_guarded(snapshot, || {
+        state.renderer_access.is_generation_current(generation)
+    })
+}
+
+#[tauri::command]
+pub fn client_state_set_restore_enabled(
+    window: WebviewWindow,
+    state: State<'_, ClientState>,
+    access_token: String,
+    enabled: bool,
+) -> Result<bool, String> {
+    let generation = validate_access(&window, &state, &access_token)?;
+    state.set_restore_enabled_guarded(enabled, || {
+        state.renderer_access.is_generation_current(generation)
+    })
+}
+
+#[tauri::command]
+pub fn client_state_clear(
+    window: WebviewWindow,
+    state: State<'_, ClientState>,
+    access_token: String,
+) -> Result<bool, String> {
+    let generation = validate_access(&window, &state, &access_token)?;
+    state.clear_guarded(|| state.renderer_access.is_generation_current(generation))
+}
+
+#[tauri::command]
+pub fn client_state_renderer_flushed(
+    app: AppHandle,
+    window: WebviewWindow,
+    state: State<'_, ClientState>,
+    access_token: String,
+    generation: u64,
+) -> Result<(), String> {
+    validate_access(&window, &state, &access_token)?;
+    crate::shutdown::renderer_flushed(app, generation);
+    Ok(())
+}
+
+#[tauri::command]
+pub fn client_state_navigation_flushed(
+    window: WebviewWindow,
+    state: State<'_, ClientState>,
+    access_token: String,
+    generation: u64,
+) -> Result<(), String> {
+    validate_access(&window, &state, &access_token)?;
+    state.acknowledge_renderer_flush(generation);
+    Ok(())
+}
diff --git a/packages/tauri-app/src-tauri/src/client_state/cross_host.rs b/packages/tauri-app/src-tauri/src/client_state/cross_host.rs
new file mode 100644
index 00000000..afeaeedc
--- /dev/null
+++ b/packages/tauri-app/src-tauri/src/client_state/cross_host.rs
@@ -0,0 +1,1467 @@
+use serde::{Deserialize, Serialize};
+use std::ffi::OsString;
+use std::fs::{self, OpenOptions};
+use std::io::Write;
+use std::path::{Path, PathBuf};
+#[cfg(any(target_os = "macos", windows))]
+use std::process::{Command, Stdio};
+#[cfg(any(target_os = "macos", windows))]
+use std::time::{Duration, Instant};
+
+const OWNER_DIRECTORY: &str = "primary.owner.json";
+const OWNER_FILENAME: &str = "owner.json";
+const PARTICIPANT_PREFIX: &str = "participant.";
+const PARTICIPANT_SUFFIX: &str = ".json";
+const RECOVERY_PREFIX: &str = "recovery.";
+const RECOVERY_SUFFIX: &str = ".claim";
+const RETIRED_PREFIX: &str = "retired.";
+const ACQUIRE_ATTEMPTS: usize = 10;
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct Owner {
+    pid: u32,
+    run_token: String,
+    process_start_identity: String,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct LegacyOwner {
+    pid: u32,
+    run_token: String,
+    process_start_identity: Option<String>,
+}
+
+pub(super) struct Registration {
+    election_directory: PathBuf,
+    participant_path: PathBuf,
+    recovery_claim: Option<PathBuf>,
+    owner: Owner,
+    legacy_electron_data: Option<PathBuf>,
+    primary: bool,
+    released: bool,
+}
+
+pub(super) fn election_directory() -> Result<PathBuf, String> {
+    resolve_election_directory_for(
+        std::env::consts::OS,
+        |name| std::env::var_os(name),
+        dirs::home_dir().as_deref(),
+    )
+    .map(PathBuf::from)
+    .ok_or_else(|| "user home directory is unavailable".to_string())
+}
+
+pub(super) fn state_path() -> Result<PathBuf, String> {
+    resolve_state_path_for(
+        std::env::consts::OS,
+        |name| std::env::var_os(name),
+        dirs::home_dir().as_deref(),
+    )
+    .map(PathBuf::from)
+    .ok_or_else(|| "user home directory is unavailable".to_string())
+}
+
+pub(super) fn legacy_electron_data_directory() -> Option<PathBuf> {
+    resolve_legacy_electron_data_directory_for(
+        std::env::consts::OS,
+        |name| std::env::var_os(name),
+        dirs::home_dir().as_deref(),
+    )
+    .map(PathBuf::from)
+}
+
+fn valid_home(value: OsString, platform: &str) -> Option<String> {
+    let value = value.into_string().ok()?;
+    let valid = if platform == "windows" {
+        let bytes = value.as_bytes();
+        (bytes.len() >= 3
+            && bytes[0].is_ascii_alphabetic()
+            && bytes[1] == b':'
+            && (bytes[2] == b'\\' || bytes[2] == b'/'))
+            || value.starts_with("\\\\")
+    } else {
+        value.starts_with('/')
+    };
+    valid.then_some(value)
+}
+
+fn configured_home(
+    platform: &str,
+    environment: &impl Fn(&str) -> Option<OsString>,
+    fallback_home: Option<&Path>,
+) -> Option<String> {
+    let configured = if platform == "windows" {
+        environment("USERPROFILE")
+            .and_then(|value| valid_home(value, platform))
+            .or_else(|| environment("HOME").and_then(|value| valid_home(value, platform)))
+    } else {
+        environment("HOME").and_then(|value| valid_home(value, platform))
+    };
+    configured.or_else(|| fallback_home.map(|path| path.to_string_lossy().into_owned()))
+}
+
+fn resolve_election_directory_for(
+    platform: &str,
+    environment: impl Fn(&str) -> Option<OsString>,
+    fallback_home: Option<&Path>,
+) -> Option<String> {
+    let home = configured_home(platform, &environment, fallback_home)?;
+    Some(if platform == "windows" {
+        format!(
+            "{}\\.codenomad\\client-state\\election",
+            home.trim_end_matches(['\\', '/'])
+        )
+    } else {
+        format!(
+            "{}/.codenomad/client-state/election",
+            home.trim_end_matches('/')
+        )
+    })
+}
+
+fn resolve_state_path_for(
+    platform: &str,
+    environment: impl Fn(&str) -> Option<OsString>,
+    fallback_home: Option<&Path>,
+) -> Option<String> {
+    let home = configured_home(platform, &environment, fallback_home)?;
+    Some(if platform == "windows" {
+        format!(
+            "{}\\.codenomad\\client-state\\client-state.json",
+            home.trim_end_matches(['\\', '/'])
+        )
+    } else {
+        format!(
+            "{}/.codenomad/client-state/client-state.json",
+            home.trim_end_matches('/')
+        )
+    })
+}
+
+fn resolve_legacy_electron_data_directory_for(
+    platform: &str,
+    environment: impl Fn(&str) -> Option<OsString>,
+    fallback_home: Option<&Path>,
+) -> Option<String> {
+    let home = configured_home(platform, &environment, fallback_home)?;
+    if platform == "windows" {
+        let root = environment("APPDATA")
+            .and_then(|value| valid_home(value, platform))
+            .unwrap_or_else(|| format!("{}\\AppData\\Roaming", home.trim_end_matches(['\\', '/'])));
+        Some(format!("{}\\CodeNomad", root.trim_end_matches(['\\', '/'])))
+    } else if platform == "macos" {
+        Some(format!(
+            "{}/Library/Application Support/CodeNomad",
+            home.trim_end_matches('/')
+        ))
+    } else {
+        let root = environment("XDG_CONFIG_HOME")
+            .and_then(|value| valid_home(value, platform))
+            .unwrap_or_else(|| format!("{}/.config", home.trim_end_matches('/')));
+        Some(format!("{}/CodeNomad", root.trim_end_matches('/')))
+    }
+}
+
+impl Registration {
+    pub(super) fn register(
+        election_directory: &Path,
+        primary_candidate: bool,
+        legacy_electron_data: Option<&Path>,
+    ) -> Result<Option<Self>, String> {
+        let Some(current_identity) = process_start_identity(std::process::id()) else {
+            return Ok(None);
+        };
+        Self::register_with_legacy(
+            election_directory,
+            Owner {
+                pid: std::process::id(),
+                run_token: uuid::Uuid::new_v4().to_string(),
+                process_start_identity: current_identity,
+            },
+            primary_candidate,
+            legacy_electron_data,
+            pid_is_alive,
+            process_start_identity,
+            expected_electron_process,
+        )
+    }
+
+    #[cfg(test)]
+    fn register_with(
+        election_directory: &Path,
+        owner: Owner,
+        primary_candidate: bool,
+        pid_alive: impl Fn(u32) -> bool + Copy,
+        identity: impl Fn(u32) -> Option<String> + Copy,
+    ) -> Result<Option<Self>, String> {
+        Self::register_with_legacy(
+            election_directory,
+            owner,
+            primary_candidate,
+            None,
+            pid_alive,
+            identity,
+            |_| Some(false),
+        )
+    }
+
+    fn register_with_legacy(
+        election_directory: &Path,
+        owner: Owner,
+        primary_candidate: bool,
+        legacy_electron_data: Option<&Path>,
+        pid_alive: impl Fn(u32) -> bool + Copy,
+        identity: impl Fn(u32) -> Option<String> + Copy,
+        expected_electron: impl Fn(u32) -> Option<bool> + Copy,
+    ) -> Result<Option<Self>, String> {
+        if !valid_token(&owner.run_token) || owner.process_start_identity.is_empty() {
+            return Ok(None);
+        }
+        fs::create_dir_all(election_directory)
+            .map_err(|err| format!("failed to create cross-host election directory: {err}"))?;
+        let participant_path = participant_path(election_directory, &owner);
+        publish_participant(&participant_path, &owner)?;
+        let mut recovery_claim = None;
+
+        let result = (|| {
+            let legacy_blocked = legacy_electron_data
+                .filter(|_| primary_candidate)
+                .map(|path| {
+                    has_live_legacy_electron_with(
+                        path,
+                        election_directory,
+                        pid_alive,
+                        identity,
+                        expected_electron,
+                    )
+                })
+                .transpose()?
+                .unwrap_or(false);
+            let mut primary = false;
+            if primary_candidate && !legacy_blocked {
+                for _ in 0..ACQUIRE_ATTEMPTS {
+                    if publish_owner(election_directory, &owner)? {
+                        primary = true;
+                        break;
+                    }
+                    let Some(observed) = read_if_exists(&owner_path(election_directory))? else {
+                        continue;
+                    };
+                    let Some(existing) = parse_owner(&observed) else {
+                        break;
+                    };
+                    if existing == owner {
+                        primary = true;
+                        break;
+                    }
+                    if owner_is_stale(&existing, pid_alive, identity) == Some(true) {
+                        let claim = recovery_path(election_directory, &owner);
+                        publish_file(&claim, &observed, "recovery claim")?;
+                        recovery_claim = Some(claim);
+                    }
+                    if !retire_owner(
+                        election_directory,
+                        &observed,
+                        &existing,
+                        &owner,
+                        pid_alive,
+                        identity,
+                    )? {
+                        break;
+                    }
+                }
+            }
+            Ok(Some(Self {
+                election_directory: election_directory.to_path_buf(),
+                participant_path: participant_path.clone(),
+                recovery_claim: recovery_claim.clone(),
+                owner: owner.clone(),
+                legacy_electron_data: legacy_electron_data.map(Path::to_path_buf),
+                primary,
+                released: false,
+            }))
+        })();
+        if result.is_err() {
+            let _ = remove_participant_if_owned(&participant_path, &owner);
+            if let Some(claim) = recovery_claim {
+                let _ = fs::remove_file(claim);
+            }
+        }
+        result
+    }
+
+    pub(super) fn is_primary(&self) -> bool {
+        if self.released || !self.primary {
+            return false;
+        }
+        let shared = read_if_exists(&owner_path(&self.election_directory))
+            .ok()
+            .flatten()
+            .and_then(|value| parse_owner(&value))
+            .is_some_and(|owner| owner == self.owner);
+        let legacy_clear = self
+            .legacy_electron_data
+            .as_deref()
+            .map(|path| {
+                has_live_legacy_electron_with(
+                    path,
+                    &self.election_directory,
+                    pid_is_alive,
+                    process_start_identity,
+                    expected_electron_process,
+                )
+            })
+            .transpose()
+            .map(|blocked| !blocked.unwrap_or(false))
+            .unwrap_or(false);
+        shared && legacy_clear
+    }
+
+    pub(super) fn release(&mut self) -> Result<bool, String> {
+        if self.released {
+            return Ok(false);
+        }
+        retire_owner_if_owned(&self.election_directory, &self.owner)?;
+        remove_participant_if_owned(&self.participant_path, &self.owner)?;
+        if let Some(claim) = &self.recovery_claim {
+            match fs::remove_file(claim) {
+                Ok(()) => {}
+                Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+                Err(err) => return Err(format!("failed to remove recovery claim: {err}")),
+            }
+        }
+        self.primary = false;
+        self.released = true;
+        Ok(true)
+    }
+}
+
+impl Drop for Registration {
+    fn drop(&mut self) {
+        if let Err(err) = self.release() {
+            eprintln!("[client-state] failed to release cross-host registration: {err}");
+        }
+    }
+}
+
+fn valid_token(token: &str) -> bool {
+    !token.is_empty()
+        && token
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || byte == b'_' || byte == b'-')
+}
+
+fn serialize_owner(owner: &Owner) -> Result<String, String> {
+    serde_json::to_string(owner).map_err(|err| err.to_string())
+}
+
+fn parse_owner(value: &str) -> Option<Owner> {
+    let owner = serde_json::from_str::<Owner>(value).ok()?;
+    (owner.pid > 0 && valid_token(&owner.run_token) && !owner.process_start_identity.is_empty())
+        .then_some(owner)
+}
+
+fn owner_path(directory: &Path) -> PathBuf {
+    directory.join(OWNER_DIRECTORY).join(OWNER_FILENAME)
+}
+
+fn participant_path(directory: &Path, owner: &Owner) -> PathBuf {
+    directory.join(format!(
+        "{PARTICIPANT_PREFIX}{}.{}{PARTICIPANT_SUFFIX}",
+        owner.pid, owner.run_token
+    ))
+}
+
+fn recovery_path(directory: &Path, owner: &Owner) -> PathBuf {
+    directory.join(format!(
+        "{RECOVERY_PREFIX}{}.{}{RECOVERY_SUFFIX}",
+        owner.pid, owner.run_token
+    ))
+}
+
+fn read_if_exists(path: &Path) -> Result<Option<String>, String> {
+    match fs::read_to_string(path) {
+        Ok(value) => Ok(Some(value)),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(err) => Err(format!(
+            "failed to read cross-host path {}: {err}",
+            path.display()
+        )),
+    }
+}
+
+fn sync(file: &fs::File) -> std::io::Result<()> {
+    match file.sync_all() {
+        Ok(()) => Ok(()),
+        Err(err) if is_unsupported_sync_error(&err) => Ok(()),
+        Err(err) => Err(err),
+    }
+}
+
+fn publish_file(path: &Path, value: &str, label: &str) -> Result<(), String> {
+    let parent = path
+        .parent()
+        .ok_or_else(|| format!("{label} path has no parent"))?;
+    let mut temporary = tempfile::NamedTempFile::new_in(parent)
+        .map_err(|err| format!("failed to create cross-host {label}: {err}"))?;
+    temporary
+        .write_all(value.as_bytes())
+        .and_then(|_| sync(temporary.as_file()))
+        .map_err(|err| format!("failed to write cross-host {label}: {err}"))?;
+    match temporary.persist_noclobber(path) {
+        Ok(_) => Ok(()),
+        Err(err) if err.error.kind() == std::io::ErrorKind::AlreadyExists => {
+            if read_if_exists(path)?.as_deref() == Some(value) {
+                Ok(())
+            } else {
+                Err(format!(
+                    "cross-host {label} path belongs to another process"
+                ))
+            }
+        }
+        Err(err) => Err(format!(
+            "failed to publish cross-host {label}: {}",
+            err.error
+        )),
+    }
+}
+
+fn publish_participant(path: &Path, owner: &Owner) -> Result<(), String> {
+    publish_file(path, &serialize_owner(owner)?, "participant")
+}
+
+fn publish_owner(directory: &Path, owner: &Owner) -> Result<bool, String> {
+    let temporary = tempfile::Builder::new()
+        .prefix(".owner.")
+        .tempdir_in(directory)
+        .map_err(|err| format!("failed to prepare cross-host owner: {err}"))?;
+    let mut file = OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(temporary.path().join(OWNER_FILENAME))
+        .map_err(|err| format!("failed to prepare cross-host owner: {err}"))?;
+    file.write_all(serialize_owner(owner)?.as_bytes())
+        .and_then(|_| sync(&file))
+        .map_err(|err| format!("failed to prepare cross-host owner: {err}"))?;
+    drop(file);
+    match fs::rename(temporary.path(), directory.join(OWNER_DIRECTORY)) {
+        Ok(()) => {
+            let _ = temporary.keep();
+            Ok(true)
+        }
+        Err(err)
+            if err.kind() == std::io::ErrorKind::AlreadyExists
+                || directory.join(OWNER_DIRECTORY).exists() =>
+        {
+            Ok(false)
+        }
+        Err(err) => Err(format!("failed to publish cross-host owner: {err}")),
+    }
+}
+
+fn owner_is_stale(
+    owner: &Owner,
+    pid_alive: impl Fn(u32) -> bool,
+    identity: impl Fn(u32) -> Option<String>,
+) -> Option<bool> {
+    if !pid_alive(owner.pid) {
+        return Some(true);
+    }
+    identity(owner.pid).map(|live| live != owner.process_start_identity)
+}
+
+fn participants(directory: &Path) -> Result<Vec<(PathBuf, Owner)>, String> {
+    let mut participants = Vec::new();
+    for entry in
+        fs::read_dir(directory).map_err(|err| format!("failed to read participants: {err}"))?
+    {
+        let entry = entry.map_err(|err| format!("failed to read participant: {err}"))?;
+        let name = entry.file_name();
+        let name = name.to_string_lossy();
+        if !name.starts_with(PARTICIPANT_PREFIX) || !name.ends_with(PARTICIPANT_SUFFIX) {
+            continue;
+        }
+        let Some(value) = read_if_exists(&entry.path())? else {
+            continue;
+        };
+        let owner = parse_owner(&value)
+            .ok_or_else(|| "cross-host participant is incomplete".to_string())?;
+        participants.push((entry.path(), owner));
+    }
+    Ok(participants)
+}
+
+fn recovery_claimants(
+    directory: &Path,
+    current: &Owner,
+    observed_owner: &str,
+    pid_alive: impl Fn(u32) -> bool + Copy,
+    identity: impl Fn(u32) -> Option<String> + Copy,
+) -> Result<Option<Vec<Owner>>, String> {
+    let mut claimants = vec![current.clone()];
+    for (path, participant) in participants(directory)? {
+        if participant == *current {
+            continue;
+        }
+        if owner_is_stale(&participant, pid_alive, identity) == Some(true) {
+            remove_participant_if_owned(&path, &participant)?;
+            match fs::remove_file(recovery_path(directory, &participant)) {
+                Ok(()) => {}
+                Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+                Err(err) => return Err(format!("failed to remove stale recovery claim: {err}")),
+            }
+            continue;
+        }
+        let claim_path = recovery_path(directory, &participant);
+        let mut claim = read_if_exists(&claim_path)?;
+        for _ in 0..20 {
+            if claim.as_deref() == Some(observed_owner) {
+                break;
+            }
+            std::thread::sleep(std::time::Duration::from_millis(5));
+            claim = read_if_exists(&claim_path)?;
+        }
+        if claim.as_deref() != Some(observed_owner) {
+            return Ok(None);
+        }
+        claimants.push(participant);
+    }
+    Ok(Some(claimants))
+}
+
+fn retire_owner(
+    directory: &Path,
+    observed: &str,
+    owner: &Owner,
+    claimant: &Owner,
+    pid_alive: impl Fn(u32) -> bool + Copy,
+    identity: impl Fn(u32) -> Option<String> + Copy,
+) -> Result<bool, String> {
+    if owner_is_stale(owner, pid_alive, identity) != Some(true) {
+        return Ok(false);
+    }
+    let Some(mut claimants) =
+        recovery_claimants(directory, claimant, observed, pid_alive, identity)?
+    else {
+        return Ok(false);
+    };
+    claimants.sort_by_key(|candidate| serialize_owner(candidate).unwrap_or_default());
+    if claimants.first() != Some(claimant)
+        || read_if_exists(&owner_path(directory))?.as_deref() != Some(observed)
+    {
+        return Ok(false);
+    }
+    let retired = directory.join(format!("{RETIRED_PREFIX}{}.{}", owner.pid, owner.run_token));
+    match fs::rename(directory.join(OWNER_DIRECTORY), &retired) {
+        Ok(()) => Ok(true),
+        Err(err)
+            if err.kind() == std::io::ErrorKind::NotFound
+                || err.kind() == std::io::ErrorKind::AlreadyExists
+                || retired.exists() =>
+        {
+            Ok(false)
+        }
+        Err(err) => Err(format!("failed to retire stale cross-host owner: {err}")),
+    }
+}
+
+fn remove_participant_if_owned(path: &Path, owner: &Owner) -> Result<(), String> {
+    if read_if_exists(path)?
+        .as_deref()
+        .and_then(parse_owner)
+        .as_ref()
+        != Some(owner)
+    {
+        return Ok(());
+    }
+    match fs::remove_file(path) {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(err) => Err(format!("failed to remove cross-host participant: {err}")),
+    }
+}
+
+fn retire_owner_if_owned(directory: &Path, owner: &Owner) -> Result<(), String> {
+    retire_owner_if_owned_with(directory, owner, || {}, || {})
+}
+
+fn retire_owner_if_owned_with(
+    directory: &Path,
+    owner: &Owner,
+    on_checked: impl FnOnce(),
+    on_retired: impl FnOnce(),
+) -> Result<(), String> {
+    let Some(observed) = read_if_exists(&owner_path(directory))? else {
+        return Ok(());
+    };
+    if parse_owner(&observed).as_ref() != Some(owner) {
+        return Ok(());
+    }
+    on_checked();
+    if read_if_exists(&owner_path(directory))?.as_deref() != Some(&observed) {
+        return Ok(());
+    }
+    let retired = directory.join(format!("{RETIRED_PREFIX}{}.{}", owner.pid, owner.run_token));
+    match fs::rename(directory.join(OWNER_DIRECTORY), &retired) {
+        Ok(()) => {}
+        Err(err)
+            if err.kind() == std::io::ErrorKind::NotFound
+                || err.kind() == std::io::ErrorKind::AlreadyExists
+                || retired.exists() =>
+        {
+            return Ok(());
+        }
+        Err(err) => return Err(format!("failed to retire owned cross-host owner: {err}")),
+    }
+    on_retired();
+    let result: Result<(), String> = (|| {
+        for entry in
+            fs::read_dir(directory).map_err(|err| format!("failed to read participants: {err}"))?
+        {
+            let entry = entry.map_err(|err| format!("failed to read participant: {err}"))?;
+            let name = entry.file_name();
+            let name = name.to_string_lossy();
+            if !name.starts_with(PARTICIPANT_PREFIX) || !name.ends_with(PARTICIPANT_SUFFIX) {
+                continue;
+            }
+            let path = entry.path();
+            let Some(observed_participant) = read_if_exists(&path)? else {
+                continue;
+            };
+            if let Some(participant) = parse_owner(&observed_participant) {
+                remove_participant_if_owned(&path, &participant)?;
+                let _ = fs::remove_file(recovery_path(directory, &participant));
+            } else if read_if_exists(&path)?.as_deref() == Some(&observed_participant) {
+                match fs::remove_file(&path) {
+                    Ok(()) => {}
+                    Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+                    Err(err) => {
+                        return Err(format!(
+                            "failed to remove malformed cross-host participant: {err}"
+                        ))
+                    }
+                }
+            }
+        }
+        Ok(())
+    })();
+    let _ = fs::remove_dir_all(retired);
+    result
+}
+
+fn has_live_legacy_electron_with(
+    directory: &Path,
+    election_directory: &Path,
+    pid_alive: impl Fn(u32) -> bool,
+    identity: impl Fn(u32) -> Option<String>,
+    expected_electron: impl Fn(u32) -> Option<bool>,
+) -> Result<bool, String> {
+    let entries = match fs::read_dir(directory) {
+        Ok(entries) => entries,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(false),
+        Err(err) => return Err(format!("failed to inspect legacy Electron markers: {err}")),
+    };
+    let upgraded: Vec<Owner> = participants(election_directory)?
+        .into_iter()
+        .map(|(_, owner)| owner)
+        .collect();
+    for entry in entries {
+        let entry =
+            entry.map_err(|err| format!("failed to inspect legacy Electron marker: {err}"))?;
+        let name = entry.file_name();
+        let name = name.to_string_lossy();
+        let Some(value) = name
+            .strip_prefix("client-state.running.")
+            .and_then(|value| value.strip_suffix(".json"))
+        else {
+            continue;
+        };
+        let Some((pid, run_token)) = value.split_once('.') else {
+            return Ok(true);
+        };
+        let Ok(pid) = pid.parse::<u32>() else {
+            return Ok(true);
+        };
+        if !pid_alive(pid) {
+            continue;
+        }
+        let marker = read_if_exists(&entry.path())?;
+        let Some(marker) = marker
+            .as_deref()
+            .and_then(|value| serde_json::from_str::<LegacyOwner>(value).ok())
+        else {
+            return Ok(true);
+        };
+        if marker.pid != pid || marker.run_token != run_token {
+            return Ok(true);
+        }
+        let live_identity = identity(pid);
+        if let Some(marker_identity) = marker.process_start_identity.as_deref() {
+            let Some(live_identity) = live_identity.as_deref() else {
+                return Ok(true);
+            };
+            if live_identity != marker_identity {
+                continue;
+            }
+            if upgraded.iter().any(|owner| {
+                owner.pid == pid
+                    && owner.run_token == run_token
+                    && owner.process_start_identity == live_identity
+            }) {
+                continue;
+            }
+            return Ok(true);
+        }
+        match expected_electron(pid) {
+            Some(false) => continue,
+            Some(true) | None => return Ok(true),
+        }
+    }
+    Ok(false)
+}
+
+fn expected_electron_process(pid: u32) -> Option<bool> {
+    let executable = process_executable(pid)?;
+    let current = std::env::current_exe().ok()?;
+    if paths_equal(&executable, &current) {
+        return Some(false);
+    }
+    let name = executable
+        .file_name()?
+        .to_string_lossy()
+        .to_ascii_lowercase();
+    Some(matches!(
+        name.as_str(),
+        "codenomad" | "codenomad.exe" | "electron" | "electron.exe"
+    ))
+}
+
+#[cfg(target_os = "linux")]
+fn process_executable(pid: u32) -> Option<PathBuf> {
+    fs::read_link(format!("/proc/{pid}/exe")).ok()
+}
+
+#[cfg(target_os = "macos")]
+fn process_executable(pid: u32) -> Option<PathBuf> {
+    command_value("ps", &["-p", &pid.to_string(), "-o", "comm="]).map(PathBuf::from)
+}
+
+#[cfg(windows)]
+fn process_executable(pid: u32) -> Option<PathBuf> {
+    command_value(
+        "powershell.exe",
+        &[
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            &format!("(Get-Process -Id {pid} -ErrorAction Stop).Path"),
+        ],
+    )
+    .map(PathBuf::from)
+}
+
+fn paths_equal(left: &Path, right: &Path) -> bool {
+    if cfg!(windows) {
+        left.to_string_lossy()
+            .eq_ignore_ascii_case(&right.to_string_lossy())
+    } else {
+        left == right
+    }
+}
+
+fn is_unsupported_sync_error(error: &std::io::Error) -> bool {
+    if error.kind() == std::io::ErrorKind::Unsupported {
+        return true;
+    }
+    #[cfg(unix)]
+    {
+        matches!(
+            error.raw_os_error(),
+            Some(libc::EINVAL) | Some(libc::ENOSYS) | Some(libc::ENOTSUP)
+        )
+    }
+    #[cfg(not(unix))]
+    false
+}
+
+#[cfg(unix)]
+fn pid_is_alive(pid: u32) -> bool {
+    let result = unsafe { libc::kill(pid as libc::pid_t, 0) };
+    result == 0 || std::io::Error::last_os_error().raw_os_error() != Some(libc::ESRCH)
+}
+
+#[cfg(windows)]
+fn pid_is_alive(pid: u32) -> bool {
+    use windows_sys::Win32::Foundation::{CloseHandle, ERROR_INVALID_PARAMETER, STILL_ACTIVE};
+    use windows_sys::Win32::System::Threading::{
+        GetExitCodeProcess, OpenProcess, PROCESS_QUERY_LIMITED_INFORMATION,
+    };
+    unsafe {
+        let process = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid);
+        if process.is_null() {
+            return windows_sys::Win32::Foundation::GetLastError() != ERROR_INVALID_PARAMETER;
+        }
+        let mut exit_code = 0;
+        let alive =
+            GetExitCodeProcess(process, &mut exit_code) == 0 || exit_code == STILL_ACTIVE as u32;
+        CloseHandle(process);
+        alive
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn process_start_identity(pid: u32) -> Option<String> {
+    let stat = fs::read_to_string(format!("/proc/{pid}/stat")).ok()?;
+    let command_end = stat.rfind(')')?;
+    let start_ticks = stat[command_end + 1..].split_whitespace().nth(19)?;
+    let boot_id = fs::read_to_string("/proc/sys/kernel/random/boot_id").ok()?;
+    let boot_id = boot_id.trim();
+    (!boot_id.is_empty()).then(|| format!("linux:{boot_id}:{start_ticks}"))
+}
+
+#[cfg(any(target_os = "macos", windows))]
+fn command_value(command: &str, args: &[&str]) -> Option<String> {
+    for _ in 0..2 {
+        let mut command = Command::new(command);
+        command
+            .args(args)
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null());
+        #[cfg(windows)]
+        {
+            use std::os::windows::process::CommandExt;
+            command.creation_flags(0x08000000);
+        }
+        let Ok(mut child) = command.spawn() else {
+            continue;
+        };
+        let deadline = Instant::now() + Duration::from_secs(5);
+        let status = loop {
+            match child.try_wait() {
+                Ok(Some(status)) => break Some(status),
+                Ok(None) if Instant::now() < deadline => {
+                    std::thread::sleep(Duration::from_millis(10))
+                }
+                _ => {
+                    let _ = child.kill();
+                    let _ = child.wait();
+                    break None;
+                }
+            }
+        };
+        if status.is_some_and(|status| status.success()) {
+            let mut value = String::new();
+            use std::io::Read;
+            if child.stdout.take()?.read_to_string(&mut value).is_ok() && !value.trim().is_empty() {
+                return Some(value.trim().to_string());
+            }
+        }
+    }
+    None
+}
+
+#[cfg(target_os = "macos")]
+fn process_start_identity(pid: u32) -> Option<String> {
+    command_value("ps", &["-p", &pid.to_string(), "-o", "lstart="])
+        .map(|value| format!("darwin:{value}"))
+}
+
+#[cfg(windows)]
+fn process_start_identity(pid: u32) -> Option<String> {
+    command_value(
+        "powershell.exe",
+        &[
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            &format!("(Get-CimInstance Win32_Process -Filter \"ProcessId = {pid}\" -ErrorAction Stop).CreationDate.ToUniversalTime().Ticks"),
+        ],
+    )
+    .map(|value| format!("win32:{value}"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashMap;
+    use std::io::{BufRead, BufReader};
+    use std::process::{Command, Stdio};
+    use std::sync::{Arc, Barrier};
+    use std::thread;
+
+    fn owner(pid: u32, token: &str, identity: &str) -> Owner {
+        Owner {
+            pid,
+            run_token: token.to_string(),
+            process_start_identity: identity.to_string(),
+        }
+    }
+
+    fn node_host(
+        election: &Path,
+        start: &Path,
+        mode: &str,
+        user_data: Option<&Path>,
+        legacy_tauri_data: Option<&Path>,
+    ) -> std::process::Child {
+        let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
+        let script =
+            manifest.join("../../electron-app/electron/main/client-state-cross-host-child.ts");
+        let mut command = Command::new("node");
+        command
+            .current_dir(manifest.join("../../.."))
+            .args(["--import", "tsx"])
+            .arg(script)
+            .arg(election)
+            .arg(start)
+            .args(["", mode]);
+        if let Some(user_data) = user_data {
+            command.arg(user_data).args(["", ""]);
+            if let Some(legacy) = legacy_tauri_data {
+                command.arg(legacy);
+            }
+        }
+        command
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()
+            .expect("Node and tsx are required for cross-language election tests")
+    }
+
+    fn node_primary(child: &mut std::process::Child) -> bool {
+        let mut line = String::new();
+        BufReader::new(child.stdout.as_mut().unwrap())
+            .read_line(&mut line)
+            .unwrap();
+        assert!(!line.is_empty());
+        serde_json::from_str::<serde_json::Value>(&line).unwrap()["acquired"]
+            .as_bool()
+            .unwrap()
+    }
+
+    fn stop_node(mut child: std::process::Child) {
+        drop(child.stdin.take());
+        let output = child.wait_with_output().unwrap();
+        assert!(
+            output.status.success(),
+            "Node host failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+
+    #[test]
+    fn simultaneous_startup_elects_one_primary() {
+        let directory = tempfile::tempdir().unwrap();
+        let start = Arc::new(Barrier::new(5));
+        let finish = Arc::new(Barrier::new(5));
+        let handles: Vec<_> = (0..4)
+            .map(|index| {
+                let directory = directory.path().to_path_buf();
+                let start = Arc::clone(&start);
+                let finish = Arc::clone(&finish);
+                thread::spawn(move || {
+                    start.wait();
+                    let registration = Registration::register_with(
+                        &directory,
+                        owner(
+                            100 + index,
+                            &format!("run-{index}"),
+                            &format!("start-{index}"),
+                        ),
+                        true,
+                        |_| true,
+                        |pid| Some(format!("start-{}", pid - 100)),
+                    )
+                    .unwrap()
+                    .unwrap();
+                    let primary = registration.is_primary();
+                    finish.wait();
+                    primary
+                })
+            })
+            .collect();
+        start.wait();
+        finish.wait();
+        assert_eq!(
+            handles
+                .into_iter()
+                .map(|handle| handle.join().unwrap())
+                .filter(|primary| *primary)
+                .count(),
+            1
+        );
+    }
+
+    #[test]
+    fn electron_and_tauri_simultaneous_startup_with_legacy_detection_elects_one() {
+        use crate::client_state::process;
+
+        let root = tempfile::tempdir().unwrap();
+        let election = root.path().join("election");
+        let node_data = root.path().join("electron");
+        let rust_data = root.path().join("tauri");
+        fs::create_dir_all(&rust_data).unwrap();
+        let start = root.path().join("start");
+        let mut node = node_host(
+            &election,
+            &start,
+            "full",
+            Some(&node_data),
+            Some(&rust_data),
+        );
+        fs::write(&start, b"").unwrap();
+        let rust = process::Registration::initialize(&rust_data, &election, Some(&node_data))
+            .unwrap()
+            .finish();
+        let node_primary = node_primary(&mut node);
+        assert_ne!(node_primary, rust.is_primary());
+        rust.release_locks();
+        stop_node(node);
+    }
+
+    #[test]
+    fn node_crash_points_leave_rust_a_safe_path_to_ownership() {
+        let owner_crash = tempfile::tempdir().unwrap();
+        let start = owner_crash.path().join("start");
+        let mut node = node_host(owner_crash.path(), &start, "owner-crash", None, None);
+        fs::write(&start, b"").unwrap();
+        assert_eq!(node.wait().unwrap().code(), Some(91));
+        let rust = Registration::register(owner_crash.path(), true, None)
+            .unwrap()
+            .unwrap();
+        assert!(rust.is_primary());
+
+        let retirement_crash = tempfile::tempdir().unwrap();
+        publish_owner(
+            retirement_crash.path(),
+            &owner(4_000_000_000, "stale", "stale-start"),
+        )
+        .unwrap();
+        let start = retirement_crash.path().join("start");
+        let mut node = node_host(retirement_crash.path(), &start, "retire-crash", None, None);
+        fs::write(&start, b"").unwrap();
+        assert_eq!(node.wait().unwrap().code(), Some(91));
+        let rust = Registration::register(retirement_crash.path(), true, None)
+            .unwrap()
+            .unwrap();
+        assert!(rust.is_primary());
+    }
+
+    #[test]
+    fn legacy_tauri_pid_reuse_does_not_veto_electron() {
+        let root = tempfile::tempdir().unwrap();
+        let election = root.path().join("election");
+        let electron_data = root.path().join("electron");
+        let legacy_tauri = root.path().join("tauri");
+        fs::create_dir_all(&legacy_tauri).unwrap();
+        fs::write(
+            legacy_tauri.join(format!(
+                "client-state.running.{}.legacy.lock",
+                std::process::id()
+            )),
+            b"",
+        )
+        .unwrap();
+        let start = root.path().join("start");
+        let mut node = node_host(
+            &election,
+            &start,
+            "full",
+            Some(&electron_data),
+            Some(&legacy_tauri),
+        );
+        fs::write(&start, b"").unwrap();
+        assert!(node_primary(&mut node));
+        stop_node(node);
+    }
+
+    #[test]
+    fn crashed_node_primary_remains_fenced_by_rust_secondary() {
+        let root = tempfile::tempdir().unwrap();
+        let start = root.path().join("start");
+        let mut node = node_host(root.path(), &start, "", None, None);
+        fs::write(&start, b"").unwrap();
+        assert!(node_primary(&mut node));
+        let mut secondary = Registration::register(root.path(), true, None)
+            .unwrap()
+            .unwrap();
+        assert!(!secondary.is_primary());
+        node.kill().unwrap();
+        node.wait().unwrap();
+
+        let mut blocked = Registration::register(root.path(), true, None)
+            .unwrap()
+            .unwrap();
+        assert!(!blocked.is_primary());
+        secondary.release().unwrap();
+        blocked.release().unwrap();
+        let successor = Registration::register(root.path(), true, None)
+            .unwrap()
+            .unwrap();
+        assert!(successor.is_primary());
+    }
+
+    #[test]
+    fn owner_publication_crash_is_invisible() {
+        let directory = tempfile::tempdir().unwrap();
+        let pending = directory.path().join(".owner.crashed.tmp");
+        fs::create_dir(&pending).unwrap();
+        fs::write(pending.join(OWNER_FILENAME), b"partial").unwrap();
+        let registration = Registration::register_with(
+            directory.path(),
+            owner(201, "winner", "winner-start"),
+            true,
+            |_| true,
+            |_| Some("winner-start".to_string()),
+        )
+        .unwrap()
+        .unwrap();
+        assert!(registration.is_primary());
+    }
+
+    #[test]
+    fn stale_retirement_crash_leaves_successor_safe() {
+        let directory = tempfile::tempdir().unwrap();
+        let stale = owner(301, "stale", "stale-start");
+        assert!(publish_owner(directory.path(), &stale).unwrap());
+        let observed = fs::read_to_string(owner_path(directory.path())).unwrap();
+        assert!(retire_owner(
+            directory.path(),
+            &observed,
+            &stale,
+            &owner(302, "claimant", "claimant-start"),
+            |_| false,
+            |_| None
+        )
+        .unwrap());
+        let successor = Registration::register_with(
+            directory.path(),
+            owner(302, "successor", "successor-start"),
+            true,
+            |_| true,
+            |_| Some("successor-start".to_string()),
+        )
+        .unwrap()
+        .unwrap();
+        assert!(successor.is_primary());
+        assert!(directory.path().join("retired.301.stale").exists());
+    }
+
+    #[test]
+    fn stale_owner_retirement_is_identity_and_cohort_guarded() {
+        for (alive, identity, recovered) in [
+            (false, None, true),
+            (true, Some("reused"), true),
+            (true, Some("old-start"), false),
+            (true, None, false),
+        ] {
+            let directory = tempfile::tempdir().unwrap();
+            publish_owner(directory.path(), &owner(401, "old", "old-start")).unwrap();
+            let registration = Registration::register_with(
+                directory.path(),
+                owner(402, "new", "new-start"),
+                true,
+                |_| alive,
+                |_| identity.map(str::to_string),
+            )
+            .unwrap()
+            .unwrap();
+            assert_eq!(registration.is_primary(), recovered);
+        }
+
+        let directory = tempfile::tempdir().unwrap();
+        publish_owner(directory.path(), &owner(501, "dead-primary", "old")).unwrap();
+        publish_participant(
+            &participant_path(
+                directory.path(),
+                &owner(502, "secondary", "secondary-start"),
+            ),
+            &owner(502, "secondary", "secondary-start"),
+        )
+        .unwrap();
+        let identities = HashMap::from([(502, "secondary-start")]);
+        let blocked = Registration::register_with(
+            directory.path(),
+            owner(503, "next", "next-start"),
+            true,
+            |pid| pid == 502,
+            |pid| identities.get(&pid).map(|value| value.to_string()),
+        )
+        .unwrap()
+        .unwrap();
+        assert!(!blocked.is_primary());
+    }
+
+    #[test]
+    fn simultaneous_claimants_deterministically_recover_a_stale_owner() {
+        let directory = tempfile::tempdir().unwrap();
+        let stale = owner(601, "stale", "stale-start");
+        let first = owner(602, "a", "a-start");
+        let second = owner(603, "b", "b-start");
+        publish_owner(directory.path(), &stale).unwrap();
+        let observed = fs::read_to_string(owner_path(directory.path())).unwrap();
+        publish_participant(&participant_path(directory.path(), &second), &second).unwrap();
+        publish_file(
+            &recovery_path(directory.path(), &second),
+            &observed,
+            "recovery claim",
+        )
+        .unwrap();
+        let identities = HashMap::from([(602, "a-start"), (603, "b-start")]);
+        let winner = Registration::register_with(
+            directory.path(),
+            first,
+            true,
+            |pid| pid != stale.pid,
+            |pid| identities.get(&pid).map(|value| value.to_string()),
+        )
+        .unwrap()
+        .unwrap();
+        let loser = Registration::register_with(
+            directory.path(),
+            second,
+            true,
+            |pid| pid != stale.pid,
+            |pid| identities.get(&pid).map(|value| value.to_string()),
+        )
+        .unwrap()
+        .unwrap();
+        assert!(winner.is_primary());
+        assert!(!loser.is_primary());
+    }
+
+    #[test]
+    fn graceful_primary_release_allows_a_successor_while_a_secondary_remains() {
+        let directory = tempfile::tempdir().unwrap();
+        let mut primary = Registration::register_with(
+            directory.path(),
+            owner(601, "primary", "primary-start"),
+            true,
+            |_| true,
+            |_| Some("primary-start".to_string()),
+        )
+        .unwrap()
+        .unwrap();
+        let secondary = Registration::register_with(
+            directory.path(),
+            owner(602, "secondary", "secondary-start"),
+            true,
+            |_| true,
+            |_| Some("primary-start".to_string()),
+        )
+        .unwrap()
+        .unwrap();
+        assert!(!secondary.is_primary());
+
+        assert!(primary.release().unwrap());
+        let successor = Registration::register_with(
+            directory.path(),
+            owner(603, "successor", "successor-start"),
+            true,
+            |_| true,
+            |_| Some("successor-start".to_string()),
+        )
+        .unwrap()
+        .unwrap();
+        assert!(successor.is_primary());
+    }
+
+    #[test]
+    fn graceful_handoff_retires_the_old_cohort_so_a_crashed_successor_can_recover() {
+        let directory = tempfile::tempdir().unwrap();
+        let secondary_owner = owner(622, "secondary", "secondary-start");
+        let successor_owner = owner(623, "successor", "successor-start");
+        let late_owner = owner(625, "late", "late-start");
+        let primary = Registration::register_with(
+            directory.path(),
+            owner(621, "primary", "primary-start"),
+            true,
+            |_| true,
+            |_| Some("primary-start".to_string()),
+        )
+        .unwrap()
+        .unwrap();
+        let _secondary = Registration::register_with(
+            directory.path(),
+            secondary_owner.clone(),
+            true,
+            |_| true,
+            |_| Some("primary-start".to_string()),
+        )
+        .unwrap()
+        .unwrap();
+
+        let malformed = directory.path().join("participant.malformed.json");
+        retire_owner_if_owned_with(
+            directory.path(),
+            &primary.owner,
+            || {
+                publish_participant(
+                    &participant_path(directory.path(), &successor_owner),
+                    &successor_owner,
+                )
+                .unwrap();
+                publish_participant(
+                    &participant_path(directory.path(), &late_owner),
+                    &late_owner,
+                )
+                .unwrap();
+                fs::write(&malformed, b"malformed").unwrap();
+            },
+            || assert!(publish_owner(directory.path(), &successor_owner).unwrap()),
+        )
+        .unwrap();
+        assert!(!directory.path().join("retired.621.primary").exists());
+        assert_eq!(
+            parse_owner(&fs::read_to_string(owner_path(directory.path())).unwrap()),
+            Some(successor_owner)
+        );
+        assert!(!participant_path(
+            directory.path(),
+            &owner(623, "successor", "successor-start")
+        )
+        .exists());
+        assert!(!participant_path(directory.path(), &late_owner).exists());
+        assert!(!malformed.exists());
+
+        let claimant_owner = owner(624, "claimant", "claimant-start");
+        let identities = HashMap::from([
+            (secondary_owner.pid, secondary_owner.process_start_identity),
+            (late_owner.pid, late_owner.process_start_identity),
+            (
+                claimant_owner.pid,
+                claimant_owner.process_start_identity.clone(),
+            ),
+        ]);
+        let claimant = Registration::register_with(
+            directory.path(),
+            claimant_owner,
+            true,
+            |pid| identities.contains_key(&pid),
+            |pid| identities.get(&pid).cloned(),
+        )
+        .unwrap()
+        .unwrap();
+        assert!(claimant.is_primary());
+    }
+
+    #[test]
+    fn non_owner_release_does_not_remove_a_live_owners_record() {
+        let directory = tempfile::tempdir().unwrap();
+        let primary_owner = owner(611, "primary", "primary-start");
+        let primary = Registration::register_with(
+            directory.path(),
+            primary_owner.clone(),
+            true,
+            |_| true,
+            |_| Some("primary-start".to_string()),
+        )
+        .unwrap()
+        .unwrap();
+        let mut secondary = Registration::register_with(
+            directory.path(),
+            owner(612, "secondary", "secondary-start"),
+            true,
+            |_| true,
+            |_| Some("primary-start".to_string()),
+        )
+        .unwrap()
+        .unwrap();
+
+        assert!(secondary.release().unwrap());
+        assert!(primary.is_primary());
+        assert_eq!(
+            parse_owner(&fs::read_to_string(owner_path(directory.path())).unwrap()),
+            Some(primary_owner)
+        );
+    }
+
+    #[test]
+    fn upgraded_markers_do_not_veto_but_unmatched_legacy_does() {
+        let election = tempfile::tempdir().unwrap();
+        let legacy = tempfile::tempdir().unwrap();
+        let upgraded = owner(701, "electron", "electron-start");
+        publish_participant(&participant_path(election.path(), &upgraded), &upgraded).unwrap();
+        fs::write(
+            legacy.path().join("client-state.running.701.electron.json"),
+            serialize_owner(&upgraded).unwrap(),
+        )
+        .unwrap();
+        assert!(!has_live_legacy_electron_with(
+            legacy.path(),
+            election.path(),
+            |_| true,
+            |_| Some("electron-start".to_string()),
+            |_| Some(true),
+        )
+        .unwrap());
+        fs::write(
+            legacy.path().join("client-state.running.702.legacy.json"),
+            r#"{"pid":702,"runToken":"legacy"}"#,
+        )
+        .unwrap();
+        assert!(has_live_legacy_electron_with(
+            legacy.path(),
+            election.path(),
+            |_| true,
+            |_| None,
+            |_| None,
+        )
+        .unwrap());
+    }
+
+    #[test]
+    fn platform_paths_match_electron() {
+        let resolve = |platform: &str, values: HashMap<&str, &str>, fallback: &str| {
+            resolve_election_directory_for(
+                platform,
+                |name| values.get(name).map(OsString::from),
+                Some(Path::new(fallback)),
+            )
+            .unwrap()
+        };
+        assert_eq!(
+            resolve("linux", HashMap::from([("HOME", "/home/dev")]), "/fallback"),
+            "/home/dev/.codenomad/client-state/election"
+        );
+        assert_eq!(
+            resolve(
+                "windows",
+                HashMap::from([("USERPROFILE", ""), ("HOME", "D:\\Home")]),
+                "C:\\Fallback"
+            ),
+            "D:\\Home\\.codenomad\\client-state\\election"
+        );
+        let resolve_state = |platform: &str, values: HashMap<&str, &str>, fallback: &str| {
+            resolve_state_path_for(
+                platform,
+                |name| values.get(name).map(OsString::from),
+                Some(Path::new(fallback)),
+            )
+            .unwrap()
+        };
+        assert_eq!(
+            resolve_state(
+                "macos",
+                HashMap::from([("HOME", "/Users/dev")]),
+                "/fallback"
+            ),
+            "/Users/dev/.codenomad/client-state/client-state.json"
+        );
+        assert_eq!(
+            resolve_state("linux", HashMap::from([("HOME", "/home/dev")]), "/fallback"),
+            "/home/dev/.codenomad/client-state/client-state.json"
+        );
+        assert_eq!(
+            resolve_state(
+                "windows",
+                HashMap::from([("USERPROFILE", ""), ("HOME", "D:\\Home")]),
+                "C:\\Fallback"
+            ),
+            "D:\\Home\\.codenomad\\client-state\\client-state.json"
+        );
+    }
+}
diff --git a/packages/tauri-app/src-tauri/src/client_state/navigation.rs b/packages/tauri-app/src-tauri/src/client_state/navigation.rs
new file mode 100644
index 00000000..ef49dbc0
--- /dev/null
+++ b/packages/tauri-app/src-tauri/src/client_state/navigation.rs
@@ -0,0 +1,321 @@
+use super::ClientState;
+use std::collections::VecDeque;
+use std::sync::{LazyLock, Mutex};
+use tauri::{AppHandle, Manager};
+use url::Url;
+
+static NAVIGATIONS: LazyLock<Mutex<NavigationQueue<NavigationOperation>>> =
+    LazyLock::new(|| Mutex::new(NavigationQueue::default()));
+
+type Operation = Box<dyn FnOnce(AppHandle) -> Result<(), String> + Send + 'static>;
+type NavigationGuard = Box<dyn Fn() -> bool + Send + 'static>;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum NavigationKind {
+    Cli,
+    Reload,
+    ForceReload,
+}
+
+struct NavigationOperation {
+    app: AppHandle,
+    target_url: Option<Url>,
+    is_current: NavigationGuard,
+    navigate: Operation,
+}
+
+struct QueuedNavigation<T> {
+    kind: NavigationKind,
+    value: T,
+}
+
+impl<T> QueuedNavigation<T> {
+    fn new(kind: NavigationKind, value: T) -> Self {
+        Self { kind, value }
+    }
+}
+
+struct NavigationQueue<T> {
+    pending: VecDeque<QueuedNavigation<T>>,
+    active: Option<NavigationKind>,
+    worker_running: bool,
+}
+
+impl<T> Default for NavigationQueue<T> {
+    fn default() -> Self {
+        Self {
+            pending: VecDeque::new(),
+            active: None,
+            worker_running: false,
+        }
+    }
+}
+
+impl<T> NavigationQueue<T> {
+    fn enqueue(&mut self, request: QueuedNavigation<T>) -> bool {
+        if request.kind != NavigationKind::Cli {
+            if self.active == Some(request.kind) || self.active == Some(NavigationKind::ForceReload)
+            {
+                return false;
+            }
+
+            if let Some(index) = self
+                .pending
+                .iter()
+                .position(|queued| queued.kind != NavigationKind::Cli)
+            {
+                if request.kind == NavigationKind::ForceReload
+                    && self.pending[index].kind == NavigationKind::Reload
+                {
+                    self.pending[index] = request;
+                }
+                return false;
+            }
+        }
+
+        if request.kind == NavigationKind::Cli {
+            let index = self
+                .pending
+                .iter()
+                .position(|queued| queued.kind != NavigationKind::Cli)
+                .unwrap_or(self.pending.len());
+            self.pending.insert(index, request);
+        } else {
+            self.pending.push_back(request);
+        }
+
+        if self.worker_running {
+            false
+        } else {
+            self.worker_running = true;
+            true
+        }
+    }
+
+    fn next(&mut self) -> Option<QueuedNavigation<T>> {
+        let request = self.pending.pop_front();
+        if let Some(request) = request.as_ref() {
+            self.active = Some(request.kind);
+        } else {
+            self.active = None;
+            self.worker_running = false;
+        }
+        request
+    }
+
+    fn complete_active(&mut self) {
+        self.active = None;
+    }
+}
+
+pub(crate) fn before_main_window_navigation(
+    app: &AppHandle,
+    kind: NavigationKind,
+    target_url: Option<Url>,
+    navigate: impl FnOnce(AppHandle) -> Result<(), String> + Send + 'static,
+) {
+    before_main_window_navigation_if(app, kind, target_url, || true, navigate);
+}
+
+pub(crate) fn before_main_window_navigation_if(
+    app: &AppHandle,
+    kind: NavigationKind,
+    target_url: Option<Url>,
+    is_current: impl Fn() -> bool + Send + 'static,
+    navigate: impl FnOnce(AppHandle) -> Result<(), String> + Send + 'static,
+) {
+    let request = QueuedNavigation::new(
+        kind,
+        NavigationOperation {
+            app: app.clone(),
+            target_url,
+            is_current: Box::new(is_current),
+            navigate: Box::new(navigate),
+        },
+    );
+    let start_worker = NAVIGATIONS
+        .lock()
+        .unwrap_or_else(|err| err.into_inner())
+        .enqueue(request);
+    if start_worker {
+        std::thread::spawn(run_navigation_queue);
+    }
+}
+
+fn run_navigation_queue() {
+    loop {
+        let request = NAVIGATIONS
+            .lock()
+            .unwrap_or_else(|err| err.into_inner())
+            .next();
+        let Some(request) = request else {
+            return;
+        };
+
+        let NavigationOperation {
+            app,
+            target_url,
+            is_current,
+            navigate,
+        } = request.value;
+        if !is_current() {
+            NAVIGATIONS
+                .lock()
+                .unwrap_or_else(|err| err.into_inner())
+                .complete_active();
+            continue;
+        }
+        if let Some(state) = app.try_state::<ClientState>() {
+            state.wait_for_renderer_flush(&app, true);
+        }
+        if !is_current() {
+            NAVIGATIONS
+                .lock()
+                .unwrap_or_else(|err| err.into_inner())
+                .complete_active();
+            continue;
+        }
+        let result = crate::shutdown::with_navigation_authority(&app, || {
+            let state = app.try_state::<ClientState>();
+            execute_navigation(state.as_deref(), target_url.as_ref(), || {
+                navigate(app.clone())
+            })
+        });
+        if let Some(Err(err)) = result {
+            eprintln!("[client-state] navigation failed: {err}");
+        }
+
+        NAVIGATIONS
+            .lock()
+            .unwrap_or_else(|err| err.into_inner())
+            .complete_active();
+    }
+}
+
+fn execute_navigation(
+    state: Option<&ClientState>,
+    target_url: Option<&Url>,
+    navigate: impl FnOnce() -> Result<(), String>,
+) -> Result<(), String> {
+    let pending = state
+        .map(|state| state.renderer_access.begin_navigation(target_url))
+        .transpose()?;
+    let result = navigate();
+    if result.is_err() {
+        if let (Some(state), Some(pending)) = (state, pending) {
+            state.renderer_access.cancel_navigation(pending);
+        }
+    }
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    use std::sync::Arc;
+
+    fn queued(kind: NavigationKind, name: &'static str) -> QueuedNavigation<&'static str> {
+        QueuedNavigation::new(kind, name)
+    }
+
+    #[test]
+    fn cli_navigation_survives_overlapping_reload_and_force_reload() {
+        let mut queue = NavigationQueue::default();
+        let cli = queued(NavigationKind::Cli, "cli");
+        assert!(queue.enqueue(cli));
+
+        let cli = queue.next().unwrap();
+        assert_eq!(cli.value, "cli");
+        let reload = queued(NavigationKind::Reload, "reload");
+        assert!(!queue.enqueue(reload));
+        let force_reload = queued(NavigationKind::ForceReload, "force reload");
+        assert!(!queue.enqueue(force_reload));
+
+        queue.complete_active();
+
+        let force_reload = queue.next().unwrap();
+        assert_eq!(force_reload.value, "force reload");
+        queue.complete_active();
+        assert!(queue.next().is_none());
+    }
+
+    #[test]
+    fn cli_requests_jump_queued_reload_without_reordering_each_other() {
+        let mut queue = NavigationQueue::default();
+        let active_cli = queued(NavigationKind::Cli, "active cli");
+        queue.enqueue(active_cli);
+        queue.next().unwrap();
+
+        let reload = queued(NavigationKind::Reload, "reload");
+        let first_cli = queued(NavigationKind::Cli, "first cli");
+        let second_cli = queued(NavigationKind::Cli, "second cli");
+        queue.enqueue(reload);
+        queue.enqueue(first_cli);
+        queue.enqueue(second_cli);
+
+        queue.complete_active();
+        assert_eq!(queue.next().unwrap().value, "first cli");
+        queue.complete_active();
+        assert_eq!(queue.next().unwrap().value, "second cli");
+        queue.complete_active();
+        assert_eq!(queue.next().unwrap().value, "reload");
+    }
+
+    #[test]
+    fn failed_navigation_preserves_renderer_access_and_runs_once() {
+        let directory = tempfile::tempdir().unwrap();
+        let state = ClientState::initialize_at(directory.path()).unwrap();
+        let renderer_url = url::Url::parse("http://127.0.0.1:43123/workspace").unwrap();
+        let calls = Arc::new(AtomicUsize::new(0));
+        state
+            .renderer_access
+            .claim("current-renderer", &renderer_url)
+            .unwrap();
+
+        let calls_for_navigation = Arc::clone(&calls);
+        let result = execute_navigation(Some(&state), Some(&renderer_url), || {
+            calls_for_navigation.fetch_add(1, Ordering::SeqCst);
+            Err("synchronous navigation failure".to_string())
+        });
+
+        assert_eq!(result, Err("synchronous navigation failure".to_string()));
+        assert_eq!(calls.load(Ordering::SeqCst), 1);
+        state
+            .renderer_access
+            .validate("current-renderer", &renderer_url)
+            .unwrap();
+    }
+
+    #[test]
+    fn accepted_navigation_rotates_renderer_access() {
+        let directory = tempfile::tempdir().unwrap();
+        let state = ClientState::initialize_at(directory.path()).unwrap();
+        let outgoing_url = url::Url::parse("http://127.0.0.1:43123/workspace").unwrap();
+        let incoming_url = url::Url::parse("http://127.0.0.1:43124/workspace").unwrap();
+        state
+            .renderer_access
+            .claim("outgoing-renderer", &outgoing_url)
+            .unwrap();
+
+        execute_navigation(Some(&state), Some(&incoming_url), || Ok(())).unwrap();
+
+        state
+            .renderer_access
+            .validate("outgoing-renderer", &outgoing_url)
+            .unwrap();
+        assert!(state.renderer_access.allows_claim_origin(&outgoing_url));
+        state
+            .renderer_access
+            .claim("incoming-renderer", &incoming_url)
+            .unwrap();
+        assert!(state
+            .renderer_access
+            .validate("outgoing-renderer", &outgoing_url)
+            .is_err());
+        state
+            .renderer_access
+            .validate("incoming-renderer", &incoming_url)
+            .unwrap();
+    }
+}
diff --git a/packages/tauri-app/src-tauri/src/client_state/process.rs b/packages/tauri-app/src-tauri/src/client_state/process.rs
new file mode 100644
index 00000000..2107c089
--- /dev/null
+++ b/packages/tauri-app/src-tauri/src/client_state/process.rs
@@ -0,0 +1,524 @@
+use fs2::FileExt;
+use std::fs::{self, File, OpenOptions};
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Mutex;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+use super::cross_host;
+
+pub(super) const PRIMARY_LOCK_FILENAME: &str = "client-state.primary.lock";
+const REGISTRATION_LOCK_FILENAME: &str = "client-state.registration.lock";
+const REGISTRATION_OWNER_FILENAME: &str = "client-state.registration.owner";
+const REGISTRATION_LOCK_TIMEOUT: Duration = Duration::from_millis(250);
+const REGISTRATION_LOCK_RETRY_DELAY: Duration = Duration::from_millis(10);
+pub(super) const RUNNING_MARKER_PREFIX: &str = "client-state.running.";
+pub(super) const RUNNING_MARKER_SUFFIX: &str = ".lock";
+
+static NEXT_RUNNING_MARKER_ID: AtomicU64 = AtomicU64::new(0);
+
+pub(super) struct ProcessState {
+    primary_lock: Mutex<Option<File>>,
+    cross_host_registration: Mutex<Option<cross_host::Registration>>,
+    running_marker: Mutex<Option<RunningMarker>>,
+    registration_file: Option<File>,
+}
+
+pub(super) struct Registration {
+    primary_lock: Option<File>,
+    cross_host_registration: Option<cross_host::Registration>,
+    running_marker: RunningMarker,
+    registration_file: File,
+    holds_registration_lock: bool,
+}
+
+impl Registration {
+    pub(super) fn initialize(
+        app_data_dir: &Path,
+        cross_host_election_dir: &Path,
+        legacy_electron_data_dir: Option<&Path>,
+    ) -> Result<Self, String> {
+        let registration_path = app_data_dir.join(REGISTRATION_LOCK_FILENAME);
+        let registration_file = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .create(true)
+            .open(&registration_path)
+            .map_err(|err| {
+                format!(
+                    "failed to open registration lock {}: {err}",
+                    registration_path.display()
+                )
+            })?;
+        let has_registration_lock =
+            try_acquire_registration_lock(&registration_file, REGISTRATION_LOCK_TIMEOUT)?;
+        if !has_registration_lock {
+            eprintln!(
+                "[client-state] registration lock timed out; continuing as a secondary client"
+            );
+        }
+
+        let registration_id = create_registration_id();
+        let registration_owner_path = app_data_dir.join(REGISTRATION_OWNER_FILENAME);
+        let acknowledged_registration = if has_registration_lock {
+            record_registration_owner(&registration_owner_path, &registration_id)?;
+            None
+        } else {
+            read_registration_owner(&registration_owner_path)
+        };
+        let running_marker =
+            create_running_marker(app_data_dir, acknowledged_registration.as_deref())?;
+        let lock_path = app_data_dir.join(PRIMARY_LOCK_FILENAME);
+        let lock_file = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .create(true)
+            .open(&lock_path)
+            .map_err(|err| format!("failed to open primary lock {}: {err}", lock_path.display()))?;
+
+        let mut primary_lock = if !has_registration_lock {
+            None
+        } else {
+            match FileExt::try_lock_exclusive(&lock_file) {
+                Ok(()) => {
+                    match has_other_live_running_markers(
+                        app_data_dir,
+                        &running_marker.path,
+                        &registration_id,
+                    ) {
+                        Ok(false) => Some(lock_file),
+                        Ok(true) => {
+                            release_primary_file(&lock_file);
+                            None
+                        }
+                        Err(err) => {
+                            eprintln!("[client-state] failed to inspect running markers: {err}");
+                            release_primary_file(&lock_file);
+                            None
+                        }
+                    }
+                }
+                Err(err) => {
+                    if !is_lock_contended(&err) {
+                        eprintln!("[client-state] failed to acquire primary lock: {err}");
+                    }
+                    None
+                }
+            }
+        };
+
+        let cross_host_registration = match cross_host::Registration::register(
+            cross_host_election_dir,
+            primary_lock.is_some(),
+            legacy_electron_data_dir,
+        ) {
+            Ok(Some(registration)) => Some(registration),
+            Ok(None) => None,
+            Err(err) => {
+                eprintln!("[client-state] failed to register cross-host ownership: {err}");
+                None
+            }
+        };
+        if !cross_host_registration
+            .as_ref()
+            .is_some_and(cross_host::Registration::is_primary)
+        {
+            if let Some(file) = primary_lock.take() {
+                release_primary_file(&file);
+            }
+        }
+
+        Ok(Self {
+            primary_lock,
+            cross_host_registration,
+            running_marker,
+            registration_file,
+            holds_registration_lock: has_registration_lock,
+        })
+    }
+
+    pub(super) fn is_primary(&self) -> bool {
+        self.primary_lock.is_some()
+            && self
+                .cross_host_registration
+                .as_ref()
+                .is_some_and(cross_host::Registration::is_primary)
+    }
+
+    pub(super) fn finish(self) -> ProcessState {
+        if self.holds_registration_lock {
+            if let Err(err) = FileExt::unlock(&self.registration_file) {
+                eprintln!("[client-state] failed to release registration lock: {err}");
+            }
+        }
+        ProcessState {
+            primary_lock: Mutex::new(self.primary_lock),
+            cross_host_registration: Mutex::new(self.cross_host_registration),
+            running_marker: Mutex::new(Some(self.running_marker)),
+            registration_file: Some(self.registration_file),
+        }
+    }
+}
+
+fn try_acquire_registration_lock(file: &File, timeout: Duration) -> Result<bool, String> {
+    let started_at = Instant::now();
+    loop {
+        match FileExt::try_lock_exclusive(file) {
+            Ok(()) => return Ok(true),
+            Err(err) if is_lock_contended(&err) => {
+                if started_at.elapsed() >= timeout {
+                    return Ok(false);
+                }
+                std::thread::sleep(REGISTRATION_LOCK_RETRY_DELAY);
+            }
+            Err(err) => return Err(format!("failed to acquire registration lock: {err}")),
+        }
+    }
+}
+
+fn create_registration_id() -> String {
+    let started_at = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_nanos();
+    format!(
+        "{}.{}.{}",
+        std::process::id(),
+        started_at,
+        NEXT_RUNNING_MARKER_ID.fetch_add(1, Ordering::Relaxed)
+    )
+}
+
+impl ProcessState {
+    pub(super) fn disabled() -> Self {
+        Self {
+            primary_lock: Mutex::new(None),
+            cross_host_registration: Mutex::new(None),
+            running_marker: Mutex::new(None),
+            registration_file: None,
+        }
+    }
+
+    pub(super) fn is_primary(&self) -> bool {
+        let has_local_lock = self
+            .primary_lock
+            .lock()
+            .map(|lock| lock.is_some())
+            .unwrap_or(false);
+        has_local_lock
+            && self
+                .cross_host_registration
+                .lock()
+                .map(|registration| {
+                    registration
+                        .as_ref()
+                        .is_some_and(cross_host::Registration::is_primary)
+                })
+                .unwrap_or(false)
+    }
+
+    pub(super) fn is_registered(&self) -> bool {
+        self.registration_file.is_some()
+    }
+
+    pub(super) fn release_locks(&self) {
+        let Some(registration_file) = &self.registration_file else {
+            return;
+        };
+        match try_acquire_registration_lock(registration_file, REGISTRATION_LOCK_TIMEOUT) {
+            Ok(true) => {}
+            Ok(false) => {
+                eprintln!(
+                    "[client-state] registration lock timed out; retaining ownership until process exit"
+                );
+                return;
+            }
+            Err(err) => {
+                eprintln!("[client-state] failed to serialize lock release: {err}");
+                return;
+            }
+        }
+        let running_marker = self
+            .running_marker
+            .lock()
+            .unwrap_or_else(|err| err.into_inner())
+            .take();
+        drop(running_marker);
+
+        let primary_lock = self
+            .primary_lock
+            .lock()
+            .unwrap_or_else(|err| err.into_inner())
+            .take();
+        if let Some(file) = primary_lock {
+            release_primary_file(&file);
+        }
+        let cross_host_registration = self
+            .cross_host_registration
+            .lock()
+            .unwrap_or_else(|err| err.into_inner())
+            .take();
+        drop(cross_host_registration);
+        if let Err(err) = FileExt::unlock(registration_file) {
+            eprintln!("[client-state] failed to release registration lock: {err}");
+        }
+    }
+}
+
+struct RunningMarker {
+    path: PathBuf,
+    file: Option<File>,
+}
+
+impl Drop for RunningMarker {
+    fn drop(&mut self) {
+        if let Some(file) = self.file.take() {
+            if let Err(err) = FileExt::unlock(&file) {
+                eprintln!("[client-state] failed to release running marker: {err}");
+            }
+            drop(file);
+        }
+        if let Err(err) = fs::remove_file(&self.path) {
+            if err.kind() != std::io::ErrorKind::NotFound {
+                eprintln!("[client-state] failed to remove running marker: {err}");
+            }
+        }
+    }
+}
+
+fn create_running_marker(
+    app_data_dir: &Path,
+    acknowledged_registration: Option<&str>,
+) -> Result<RunningMarker, String> {
+    loop {
+        let marker = tempfile::Builder::new()
+            .prefix(".client-state.running.pending.")
+            .tempfile_in(app_data_dir)
+            .map_err(|err| format!("failed to create running marker: {err}"))?;
+        FileExt::try_lock_exclusive(marker.as_file())
+            .map_err(|err| format!("failed to lock running marker: {err}"))?;
+        let marker_id = NEXT_RUNNING_MARKER_ID.fetch_add(1, Ordering::Relaxed);
+        let acknowledgement = acknowledged_registration
+            .map(|registration_id| format!(".acknowledges.{registration_id}"))
+            .unwrap_or_default();
+        let path = app_data_dir.join(format!(
+            "{RUNNING_MARKER_PREFIX}{}.{marker_id}{acknowledgement}{RUNNING_MARKER_SUFFIX}",
+            std::process::id()
+        ));
+        match marker.persist_noclobber(&path) {
+            Ok(file) => {
+                return Ok(RunningMarker {
+                    path,
+                    file: Some(file),
+                });
+            }
+            Err(err) if err.error.kind() == std::io::ErrorKind::AlreadyExists => continue,
+            Err(err) => {
+                return Err(format!("failed to publish running marker: {}", err.error));
+            }
+        }
+    }
+}
+
+fn has_other_live_running_markers(
+    app_data_dir: &Path,
+    current_marker_path: &Path,
+    registration_id: &str,
+) -> Result<bool, String> {
+    let entries = fs::read_dir(app_data_dir)
+        .map_err(|err| format!("failed to read {}: {err}", app_data_dir.display()))?;
+    let mut has_live_marker = false;
+
+    for entry in entries {
+        let entry = entry.map_err(|err| format!("failed to read directory entry: {err}"))?;
+        let path = entry.path();
+        let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
+            continue;
+        };
+        if path == current_marker_path
+            || !name.starts_with(RUNNING_MARKER_PREFIX)
+            || !name.ends_with(RUNNING_MARKER_SUFFIX)
+        {
+            continue;
+        }
+
+        let file = match OpenOptions::new().read(true).write(true).open(&path) {
+            Ok(file) => file,
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(err) => {
+                return Err(format!(
+                    "failed to open running marker {}: {err}",
+                    path.display()
+                ));
+            }
+        };
+        match FileExt::try_lock_exclusive(&file) {
+            Ok(()) => {
+                if let Err(err) = FileExt::unlock(&file) {
+                    eprintln!("[client-state] failed to unlock stale running marker: {err}");
+                }
+                drop(file);
+                if let Err(err) = fs::remove_file(&path) {
+                    if err.kind() != std::io::ErrorKind::NotFound {
+                        eprintln!("[client-state] failed to remove stale running marker: {err}");
+                    }
+                }
+            }
+            Err(err) if is_lock_contended(&err) => {
+                if !name.ends_with(&format!(
+                    ".acknowledges.{registration_id}{RUNNING_MARKER_SUFFIX}"
+                )) {
+                    has_live_marker = true;
+                }
+            }
+            Err(err) => {
+                return Err(format!(
+                    "failed to inspect running marker {}: {err}",
+                    path.display()
+                ));
+            }
+        }
+    }
+
+    Ok(has_live_marker)
+}
+
+fn record_registration_owner(path: &Path, registration_id: &str) -> Result<(), String> {
+    fs::write(path, registration_id)
+        .map_err(|err| format!("failed to record registration owner: {err}"))
+}
+
+fn read_registration_owner(path: &Path) -> Option<String> {
+    let owner = fs::read_to_string(path).ok()?;
+    (!owner.is_empty()).then_some(owner)
+}
+
+fn release_primary_file(file: &File) {
+    if let Err(err) = FileExt::unlock(file) {
+        eprintln!("[client-state] failed to release primary lock: {err}");
+    }
+}
+
+fn is_lock_contended(error: &std::io::Error) -> bool {
+    let expected = fs2::lock_contended_error();
+    error.kind() == std::io::ErrorKind::WouldBlock
+        || (error.raw_os_error().is_some() && error.raw_os_error() == expected.raw_os_error())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn registration_lock_contention_times_out() {
+        let directory = tempfile::tempdir().unwrap();
+        let path = directory.path().join(REGISTRATION_LOCK_FILENAME);
+        let owner = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .create(true)
+            .open(&path)
+            .unwrap();
+        FileExt::lock_exclusive(&owner).unwrap();
+        let contender = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(&path)
+            .unwrap();
+
+        let started_at = Instant::now();
+        assert!(!try_acquire_registration_lock(&contender, Duration::from_millis(20)).unwrap());
+        assert!(started_at.elapsed() < Duration::from_secs(1));
+
+        FileExt::unlock(&owner).unwrap();
+    }
+
+    #[test]
+    fn registration_timeout_initializes_a_secondary_process() {
+        let directory = tempfile::tempdir().unwrap();
+        let path = directory.path().join(REGISTRATION_LOCK_FILENAME);
+        let owner = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .create(true)
+            .open(&path)
+            .unwrap();
+        FileExt::lock_exclusive(&owner).unwrap();
+        let registration_id = "registering-process";
+        record_registration_owner(
+            &directory.path().join(REGISTRATION_OWNER_FILENAME),
+            registration_id,
+        )
+        .unwrap();
+
+        let started_at = Instant::now();
+        let registration =
+            Registration::initialize(directory.path(), &directory.path().join("cross-host"), None)
+                .unwrap();
+        assert!(!registration.is_primary());
+        assert!(started_at.elapsed() < Duration::from_secs(2));
+        let marker_name = registration
+            .running_marker
+            .path
+            .file_name()
+            .unwrap()
+            .to_string_lossy();
+        assert!(marker_name.contains(&format!(".acknowledges.{registration_id}")));
+
+        FileExt::unlock(&owner).unwrap();
+        registration.finish().release_locks();
+    }
+
+    #[test]
+    fn process_release_waits_for_registration_election() {
+        use std::sync::{mpsc, Arc};
+
+        let directory = tempfile::tempdir().unwrap();
+        let registration =
+            Registration::initialize(directory.path(), &directory.path().join("cross-host"), None)
+                .unwrap();
+        assert!(registration.is_primary());
+        let process = Arc::new(registration.finish());
+        let registration_file = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(directory.path().join(REGISTRATION_LOCK_FILENAME))
+            .unwrap();
+        FileExt::lock_exclusive(&registration_file).unwrap();
+
+        let releasing_process = Arc::clone(&process);
+        let (released_tx, released_rx) = mpsc::channel();
+        let release = std::thread::spawn(move || {
+            releasing_process.release_locks();
+            released_tx.send(()).unwrap();
+        });
+        assert_eq!(
+            released_rx.recv_timeout(Duration::from_millis(50)),
+            Err(mpsc::RecvTimeoutError::Timeout)
+        );
+
+        FileExt::unlock(&registration_file).unwrap();
+        released_rx.recv_timeout(Duration::from_secs(1)).unwrap();
+        release.join().unwrap();
+        assert!(!process.is_primary());
+    }
+
+    #[test]
+    fn registering_process_ignores_timeout_marker_that_acknowledges_it() {
+        let directory = tempfile::tempdir().unwrap();
+        let registration_id = "registering-process";
+        let registering_marker = create_running_marker(directory.path(), None).unwrap();
+        let timeout_marker =
+            create_running_marker(directory.path(), Some(registration_id)).unwrap();
+
+        assert!(!has_other_live_running_markers(
+            directory.path(),
+            &registering_marker.path,
+            registration_id,
+        )
+        .unwrap());
+
+        drop(timeout_marker);
+        drop(registering_marker);
+    }
+}
diff --git a/packages/tauri-app/src-tauri/src/client_state/tests.rs b/packages/tauri-app/src-tauri/src/client_state/tests.rs
new file mode 100644
index 00000000..a2a7d618
--- /dev/null
+++ b/packages/tauri-app/src-tauri/src/client_state/tests.rs
@@ -0,0 +1,742 @@
+use super::commands::is_allowed_client_state_origin;
+use super::process::{PRIMARY_LOCK_FILENAME, RUNNING_MARKER_PREFIX, RUNNING_MARKER_SUFFIX};
+use super::window::{
+    clamp_window_bounds, normalize_native_zoom_level, DisplayArea, NativeWindowState, WindowBounds,
+    MAX_ZOOM_LEVEL,
+};
+use super::{
+    parse_client_state, ClientState, ClientStateLoadResult, CLIENT_STATE_FILENAME,
+    DEFAULT_ZOOM_LEVEL, MAX_CLIENT_SNAPSHOT_BYTES,
+};
+use serde_json::{json, Value};
+use std::fs;
+use std::io::{BufRead, BufReader};
+use std::process::{Command, Stdio};
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::{mpsc, Arc, Barrier};
+use std::thread;
+use std::time::Duration;
+use tempfile::TempDir;
+use url::Url;
+
+fn load(is_primary: bool, restore_enabled: bool, snapshot: Value) -> ClientStateLoadResult {
+    ClientStateLoadResult {
+        is_primary,
+        restore_enabled,
+        snapshot,
+    }
+}
+
+fn assert_access_rejected(state: &ClientState, token: &str, url: &Url) {
+    assert!(state.renderer_access.validate(token, url).is_err());
+}
+
+fn acknowledged_generation(state: &ClientState) -> u64 {
+    state
+        .renderer_flush
+        .acknowledged_generation
+        .load(Ordering::SeqCst)
+}
+
+fn assert_receive_timeout<T>(result: Result<T, mpsc::RecvTimeoutError>) {
+    assert!(matches!(result, Err(mpsc::RecvTimeoutError::Timeout)));
+}
+
+fn enable_restore(state: &ClientState) {
+    assert!(state.set_restore_enabled(true).unwrap());
+}
+
+fn enable_restore_in_memory(state: &ClientState) {
+    let mut persisted = state.state.lock().unwrap();
+    persisted.restore_enabled = true;
+    persisted.writes_enabled = true;
+}
+
+fn failing_state(initially_failing: bool) -> (TempDir, ClientState, Arc<AtomicBool>) {
+    let directory = tempfile::tempdir().unwrap();
+    let fail = Arc::new(AtomicBool::new(initially_failing));
+    let writer_flag = Arc::clone(&fail);
+    let state = ClientState::initialize_at_with_writer(
+        directory.path(),
+        Arc::new(move |path, bytes, ownership_valid| {
+            if writer_flag.load(Ordering::SeqCst) {
+                Err("injected write failure".to_string())
+            } else {
+                super::write_atomically(path, bytes, ownership_valid)
+            }
+        }),
+    )
+    .unwrap();
+    (directory, state, fail)
+}
+fn window() -> NativeWindowState {
+    NativeWindowState {
+        bounds: bounds(20, 30, 1400, 900),
+        maximized: true,
+        fullscreen: false,
+        zoom_factor: 2.0,
+    }
+}
+fn bounds(x: i32, y: i32, width: i32, height: i32) -> WindowBounds {
+    WindowBounds {
+        x,
+        y,
+        width,
+        height,
+    }
+}
+fn display(x: i32, y: i32, width: u32, height: u32) -> DisplayArea {
+    DisplayArea {
+        x,
+        y,
+        width,
+        height,
+    }
+}
+fn concurrent_roles(path: &std::path::Path, count: usize) -> Vec<bool> {
+    let start = Arc::new(Barrier::new(count + 1));
+    let release = Arc::new(Barrier::new(count + 1));
+    let (sender, receiver) = mpsc::channel();
+    let handles: Vec<_> = (0..count)
+        .map(|_| {
+            let path = path.to_path_buf();
+            let start = Arc::clone(&start);
+            let release = Arc::clone(&release);
+            let sender = sender.clone();
+            thread::spawn(move || {
+                start.wait();
+                let state = ClientState::initialize_at(&path).unwrap();
+                sender.send(state.is_primary()).unwrap();
+                release.wait();
+            })
+        })
+        .collect();
+    drop(sender);
+    start.wait();
+    let roles = (0..count).map(|_| receiver.recv().unwrap()).collect();
+    release.wait();
+    for handle in handles {
+        handle.join().unwrap();
+    }
+    roles
+}
+
+fn run_node_state_host(
+    election: &std::path::Path,
+    electron_data: &std::path::Path,
+    tauri_data: &std::path::Path,
+    operation: &str,
+    payload: Option<&Value>,
+) -> Value {
+    let root = election.parent().unwrap();
+    fs::create_dir_all(root).unwrap();
+    let start = root.join(format!("node-start-{operation}"));
+    let script = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("../../electron-app/electron/main/client-state-cross-host-child.ts");
+    let mut child = Command::new("node")
+        .current_dir(std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../.."))
+        .args(["--import", "tsx"])
+        .arg(script)
+        .arg(election)
+        .arg(&start)
+        .args(["", "full"])
+        .arg(electron_data)
+        .args(["", ""])
+        .arg(tauri_data)
+        .arg(operation)
+        .arg(payload.map(Value::to_string).unwrap_or_default())
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("Node and tsx are required for cross-language state tests");
+    fs::write(start, b"").unwrap();
+    let mut line = String::new();
+    BufReader::new(child.stdout.as_mut().unwrap())
+        .read_line(&mut line)
+        .unwrap();
+    drop(child.stdin.take());
+    let output = child.wait_with_output().unwrap();
+    assert!(
+        output.status.success(),
+        "Node host failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    serde_json::from_str(&line).unwrap()
+}
+#[test]
+fn restore_defaults_on_unless_explicitly_disabled() {
+    let directory = tempfile::tempdir().unwrap();
+    let state = ClientState::initialize_at(directory.path()).unwrap();
+    assert_eq!(state.load().unwrap(), load(true, true, Value::Null));
+    assert!(state.save_snapshot(json!({ "saved": true })).unwrap());
+
+    let disabled_directory = tempfile::tempdir().unwrap();
+    fs::write(
+        disabled_directory.path().join(CLIENT_STATE_FILENAME),
+        br#"{"version":1,"restoreEnabled":false}"#,
+    )
+    .unwrap();
+    let disabled = ClientState::initialize_at(disabled_directory.path()).unwrap();
+    assert_eq!(disabled.load().unwrap(), load(true, false, Value::Null));
+}
+
+#[test]
+fn parses_envelopes_and_normalizes_zoom() {
+    for bytes in [
+        br#"not json"#.as_slice(),
+        br#"{"version":0,"restoreEnabled":false}"#.as_slice(),
+        br#"{"version":1,"restoreEnabled":"no"}"#.as_slice(),
+    ] {
+        let state = parse_client_state(bytes);
+        assert!(state.restore_enabled);
+        assert_eq!(state.snapshot, None);
+        assert!(!state.unsupported_future_envelope);
+    }
+    let state = parse_client_state(
+        br#"{"version":1,"restoreEnabled":false,"snapshot":{"folder":"work"},"window":{"bounds":{"x":20,"y":30,"width":1400,"height":900},"maximized":true,"fullscreen":false,"zoomFactor":20}}"#,
+    );
+    assert!(!state.restore_enabled);
+    assert_eq!(state.snapshot, Some(json!({ "folder": "work" })));
+    assert_eq!(state.window.unwrap().zoom_factor, MAX_ZOOM_LEVEL);
+    for (input, expected) in [
+        (1.25, Some(1.25)),
+        (0.01, Some(0.25)),
+        (20.0, Some(MAX_ZOOM_LEVEL)),
+        (0.0, None),
+        (-1.0, None),
+        (f64::NAN, None),
+        (f64::INFINITY, None),
+    ] {
+        assert_eq!(normalize_native_zoom_level(input), expected);
+    }
+}
+
+#[test]
+fn migrates_dual_legacy_files_with_disabled_dominance_and_malformed_fallback() {
+    for malformed_electron in [false, true] {
+        let root = tempfile::tempdir().unwrap();
+        let electron = root.path().join("electron");
+        let tauri = root.path().join("tauri");
+        let election = root.path().join("shared/election");
+        let shared = root.path().join("shared/client-state.json");
+        fs::create_dir_all(&electron).unwrap();
+        fs::create_dir_all(&tauri).unwrap();
+        fs::write(
+            electron.join(CLIENT_STATE_FILENAME),
+            if malformed_electron {
+                b"malformed".to_vec()
+            } else {
+                serde_json::to_vec(&json!({
+                    "version": 1,
+                    "restoreEnabled": true,
+                    "snapshot": { "revision": 999, "savedAt": 20, "host": "electron" }
+                }))
+                .unwrap()
+            },
+        )
+        .unwrap();
+        fs::write(
+            tauri.join(CLIENT_STATE_FILENAME),
+            serde_json::to_vec(&json!({
+                "version": 1,
+                "restoreEnabled": false,
+                "snapshot": { "savedAt": 1, "host": "tauri" }
+            }))
+            .unwrap(),
+        )
+        .unwrap();
+        let state = ClientState::initialize_at_with_writer_and_election(
+            &tauri,
+            &election,
+            &shared,
+            Some(&electron),
+            Arc::new(super::write_atomically),
+        )
+        .unwrap();
+        assert_eq!(state.load().unwrap(), load(true, false, Value::Null));
+        assert!(!parse_client_state(&fs::read(&shared).unwrap()).restore_enabled);
+        assert!(!electron.join(CLIENT_STATE_FILENAME).exists());
+        assert!(!tauri.join(CLIENT_STATE_FILENAME).exists());
+    }
+
+    let root = tempfile::tempdir().unwrap();
+    let electron = root.path().join("electron");
+    let tauri = root.path().join("tauri");
+    let election = root.path().join("shared/election");
+    let shared = root.path().join("shared/client-state.json");
+    fs::create_dir_all(&electron).unwrap();
+    fs::create_dir_all(&tauri).unwrap();
+    fs::write(
+        electron.join(CLIENT_STATE_FILENAME),
+        serde_json::to_vec(&json!({ "version": 1, "restoreEnabled": true })).unwrap(),
+    )
+    .unwrap();
+    fs::write(
+        tauri.join(CLIENT_STATE_FILENAME),
+        serde_json::to_vec(&json!({
+            "version": 1,
+            "restoreEnabled": true,
+            "snapshot": { "savedAt": 20 }
+        }))
+        .unwrap(),
+    )
+    .unwrap();
+    let state = ClientState::initialize_at_with_writer_and_election(
+        &tauri,
+        &election,
+        &shared,
+        Some(&electron),
+        Arc::new(super::write_atomically),
+    )
+    .unwrap();
+    assert_eq!(state.load().unwrap().snapshot, Value::Null);
+}
+
+#[test]
+fn electron_and_tauri_share_the_complete_envelope_across_handoffs() {
+    let root = tempfile::tempdir().unwrap();
+    let electron = root.path().join("electron");
+    let tauri = root.path().join("tauri");
+    let election = root.path().join("shared/election");
+    let shared = root.path().join("shared/client-state.json");
+    fs::create_dir_all(&electron).unwrap();
+    fs::create_dir_all(&tauri).unwrap();
+
+    let electron_snapshot = json!({ "version": 0, "savedAt": 10, "from": "electron" });
+    let node = run_node_state_host(
+        &election,
+        &electron,
+        &tauri,
+        "save",
+        Some(&electron_snapshot),
+    );
+    assert_eq!(node["acquired"], true);
+    let rust = ClientState::initialize_at_with_writer_and_election(
+        &tauri,
+        &election,
+        &shared,
+        Some(&electron),
+        Arc::new(super::write_atomically),
+    )
+    .unwrap();
+    assert_eq!(rust.load().unwrap().snapshot, electron_snapshot);
+    let tauri_snapshot = json!({ "savedAt": 20, "from": "tauri" });
+    assert!(rust.save_snapshot(tauri_snapshot.clone()).unwrap());
+    rust.release_locks();
+    assert!(!election.join("primary.owner.json").exists());
+
+    let node = run_node_state_host(&election, &electron, &tauri, "load", None);
+    assert_eq!(node["acquired"], true);
+    assert_eq!(node["state"]["snapshot"], tauri_snapshot);
+}
+#[test]
+fn normalizes_window_bounds_against_displays() {
+    let cases = [
+        (
+            bounds(4000, 2000, 1400, 900),
+            vec![display(0, 0, 1920, 1080)],
+            bounds(520, 180, 1400, 900),
+        ),
+        (
+            bounds(-2000, 100, 3000, 300),
+            vec![display(-1280, 0, 1280, 1024), display(0, 0, 1920, 1080)],
+            bounds(-1280, 100, 1280, 600),
+        ),
+    ];
+    for (bounds, displays, expected) in cases {
+        assert_eq!(clamp_window_bounds(&bounds, &displays), Some(expected));
+    }
+}
+#[test]
+fn stale_files_recover_without_trusting_pid_identity() {
+    for lock_contents in [
+        b"{\"pid\":999999}".as_slice(),
+        b"{\"pid\":0}",
+        b"inconclusive",
+    ] {
+        let directory = tempfile::tempdir().unwrap();
+        fs::write(directory.path().join(PRIMARY_LOCK_FILENAME), lock_contents).unwrap();
+        let marker = directory.path().join(format!(
+            "{RUNNING_MARKER_PREFIX}stale{RUNNING_MARKER_SUFFIX}"
+        ));
+        fs::write(&marker, b"").unwrap();
+        let state = ClientState::initialize_at(directory.path()).unwrap();
+        assert!(state.is_primary());
+        assert!(!marker.exists());
+    }
+}
+#[test]
+fn election_preserves_cohorts_until_every_participant_exits() {
+    let directory = tempfile::tempdir().unwrap();
+    assert_eq!(
+        concurrent_roles(directory.path(), 2)
+            .iter()
+            .filter(|role| **role)
+            .count(),
+        1
+    );
+    fs::remove_dir_all(directory.path().join(".cross-host-election")).unwrap();
+    let primary = ClientState::initialize_at(directory.path()).unwrap();
+    let secondary = ClientState::initialize_at(directory.path()).unwrap();
+    assert!(primary.is_primary());
+    assert!(!secondary.is_primary());
+    drop(primary);
+    assert_eq!(concurrent_roles(directory.path(), 2), [false, false]);
+    let waiting = ClientState::initialize_at(directory.path()).unwrap();
+    assert!(!waiting.is_primary());
+    drop(secondary);
+    drop(waiting);
+    // Thread-backed clients share this test process identity; real exited hosts do not.
+    fs::remove_dir_all(directory.path().join(".cross-host-election")).unwrap();
+    assert!(ClientState::initialize_at(directory.path())
+        .unwrap()
+        .is_primary());
+}
+#[test]
+fn secondary_and_failed_initialization_are_isolated() {
+    let directory = tempfile::tempdir().unwrap();
+    let primary = ClientState::initialize_at(directory.path()).unwrap();
+    enable_restore(&primary);
+    assert!(primary.save_snapshot(json!({ "kept": true })).unwrap());
+    let state_path = directory.path().join(CLIENT_STATE_FILENAME);
+    let original = fs::read(&state_path).unwrap();
+    let secondary = ClientState::initialize_at(directory.path()).unwrap();
+    assert_eq!(secondary.load().unwrap(), load(false, true, Value::Null));
+    assert!(!secondary.save_snapshot(json!({ "replace": true })).unwrap());
+    assert!(!secondary.set_restore_enabled(false).unwrap());
+    assert!(!secondary.clear().unwrap());
+    assert_eq!(fs::read(state_path).unwrap(), original);
+    let invalid = directory.path().join("not-a-directory");
+    fs::write(&invalid, b"occupied").unwrap();
+    let disabled = ClientState::initialize_managed_at(&invalid);
+    assert_eq!(disabled.load().unwrap(), load(false, false, Value::Null));
+    assert!(!disabled.save_snapshot(json!({ "ignored": true })).unwrap());
+}
+#[test]
+fn disable_and_clear_suppress_later_writes() {
+    for clear in [false, true] {
+        let directory = tempfile::tempdir().unwrap();
+        let state = ClientState::initialize_at(directory.path()).unwrap();
+        enable_restore(&state);
+        assert!(state.save_snapshot(json!({ "removed": true })).unwrap());
+        state.state.lock().unwrap().window = Some(window());
+        if clear {
+            assert!(state.clear().unwrap());
+            assert_eq!(state.load().unwrap(), load(true, true, Value::Null));
+        } else {
+            assert!(state.set_restore_enabled(false).unwrap());
+            assert_eq!(state.load().unwrap(), load(true, false, Value::Null));
+            assert_eq!(*state.zoom_level.lock().unwrap(), DEFAULT_ZOOM_LEVEL);
+        }
+        let path = directory.path().join(CLIENT_STATE_FILENAME);
+        let persisted = parse_client_state(&fs::read(&path).unwrap());
+        assert_eq!(persisted.snapshot, None);
+        assert_eq!(persisted.window, None);
+        let bytes = fs::read(&path).unwrap();
+        assert!(state.save_snapshot(json!({ "ignored": true })).unwrap());
+        assert_eq!(fs::read(path).unwrap(), bytes);
+    }
+}
+#[test]
+fn failed_writes_restore_memory_and_suppression_state() {
+    for operation in ["snapshot", "clear", "disable"] {
+        let (_directory, state, fail) = failing_state(false);
+        enable_restore(&state);
+        assert!(state.save_snapshot(json!({ "kept": true })).unwrap());
+        state.state.lock().unwrap().window = Some(window());
+        fail.store(true, Ordering::SeqCst);
+        let error = match operation {
+            "snapshot" => state.save_snapshot(json!({ "lost": true })).unwrap_err(),
+            "clear" => state.clear().unwrap_err(),
+            _ => state.set_restore_enabled(false).unwrap_err(),
+        };
+        assert_eq!(error, "injected write failure");
+        assert_eq!(
+            state.load().unwrap(),
+            load(true, true, json!({ "kept": true }))
+        );
+        assert!(state.state.lock().unwrap().window.is_some());
+        assert!(state.state.lock().unwrap().writes_enabled);
+        fail.store(false, Ordering::SeqCst);
+        assert!(state.save_snapshot(json!({ "replacement": true })).unwrap());
+    }
+    let (_directory, state, fail) = failing_state(false);
+    state.clear().unwrap();
+    fail.store(true, Ordering::SeqCst);
+    assert_eq!(
+        state.set_restore_enabled(true).unwrap_err(),
+        "injected write failure"
+    );
+    assert!(state.save_snapshot(json!({ "ignored": true })).unwrap());
+    assert_eq!(state.load().unwrap().snapshot, Value::Null);
+}
+#[test]
+fn future_envelope_is_preserved_until_successful_clear() {
+    let directory = tempfile::tempdir().unwrap();
+    let path = directory.path().join(CLIENT_STATE_FILENAME);
+    let future = br#"{"version":9,"snapshot":{"future":true},"extension":{"keep":"exactly"}}"#;
+    fs::write(&path, future).unwrap();
+    let fail = Arc::new(AtomicBool::new(true));
+    let count = Arc::new(AtomicUsize::new(0));
+    let writer_fail = Arc::clone(&fail);
+    let writer_count = Arc::clone(&count);
+    let state = ClientState::initialize_at_with_writer(
+        directory.path(),
+        Arc::new(move |path, bytes, ownership_valid| {
+            writer_count.fetch_add(1, Ordering::SeqCst);
+            if writer_fail.load(Ordering::SeqCst) {
+                Err("injected write failure".to_string())
+            } else {
+                super::write_atomically(path, bytes, ownership_valid)
+            }
+        }),
+    )
+    .unwrap();
+    assert_eq!(state.load().unwrap(), load(true, false, Value::Null));
+    assert!(!state.set_restore_enabled(false).unwrap());
+    assert!(state.save_snapshot(json!({ "ignored": true })).unwrap());
+    state.flush().unwrap();
+    assert_eq!(count.load(Ordering::SeqCst), 0);
+    assert_eq!(state.clear().unwrap_err(), "injected write failure");
+    assert_eq!(fs::read(&path).unwrap(), future);
+    assert!(state.state.lock().unwrap().unsupported_future_envelope);
+    fail.store(false, Ordering::SeqCst);
+    assert!(state.clear().unwrap());
+    assert!(!state.state.lock().unwrap().unsupported_future_envelope);
+    enable_restore(&state);
+    assert!(state.save_snapshot(json!({ "accepted": true })).unwrap());
+    assert_eq!(state.load().unwrap().snapshot, json!({ "accepted": true }));
+}
+#[test]
+fn renderer_tokens_and_origins_are_isolated_across_navigation() {
+    let directory = tempfile::tempdir().unwrap();
+    let state = ClientState::initialize_at(directory.path()).unwrap();
+    let outgoing = Url::parse("http://127.0.0.1:43123/workspace").unwrap();
+    let incoming = Url::parse("http://127.0.0.1:43124/workspace").unwrap();
+    assert!(state.renderer_access.claim("", &outgoing).is_err());
+    assert_access_rejected(&state, "missing", &outgoing);
+    state.renderer_access.claim("outgoing", &outgoing).unwrap();
+    assert!(state.renderer_access.claim("other", &outgoing).is_err());
+    assert_access_rejected(&state, "outgoing", &incoming);
+    state
+        .renderer_access
+        .begin_navigation(Some(&incoming))
+        .unwrap();
+    state
+        .renderer_access
+        .validate("outgoing", &outgoing)
+        .unwrap();
+    state.renderer_access.claim("incoming", &incoming).unwrap();
+    assert_access_rejected(&state, "outgoing", &outgoing);
+    state
+        .renderer_access
+        .validate("incoming", &incoming)
+        .unwrap();
+    for (url, managed, allowed) in [
+        (&outgoing, Some("http://127.0.0.1:43123"), true),
+        (&incoming, Some("http://127.0.0.1:43123"), false),
+        (
+            &Url::parse("http://localhost:9000/workspace").unwrap(),
+            None,
+            false,
+        ),
+        (
+            &Url::parse("https://tauri.localhost/loading.html").unwrap(),
+            None,
+            true,
+        ),
+    ] {
+        assert_eq!(is_allowed_client_state_origin(url, managed), allowed);
+    }
+    for url in ["file:///tmp/loading.html", "about:blank"] {
+        assert!(state
+            .renderer_access
+            .claim("opaque", &Url::parse(url).unwrap())
+            .is_err());
+    }
+}
+
+#[test]
+fn reload_preserves_pending_cross_origin_authority_until_incoming_claim() {
+    let directory = tempfile::tempdir().unwrap();
+    let state = ClientState::initialize_at(directory.path()).unwrap();
+    let outgoing = Url::parse("http://127.0.0.1:43123/workspace").unwrap();
+    let incoming = Url::parse("http://127.0.0.1:43124/workspace").unwrap();
+    state.renderer_access.claim("outgoing", &outgoing).unwrap();
+
+    state
+        .renderer_access
+        .begin_navigation(Some(&incoming))
+        .unwrap();
+    state.renderer_access.begin_navigation(None).unwrap();
+
+    state.renderer_access.claim("incoming", &incoming).unwrap();
+    state
+        .renderer_access
+        .validate("incoming", &incoming)
+        .unwrap();
+}
+
+#[test]
+fn failed_follow_up_navigation_restores_previous_pending_authority() {
+    let directory = tempfile::tempdir().unwrap();
+    let state = ClientState::initialize_at(directory.path()).unwrap();
+    let outgoing = Url::parse("http://127.0.0.1:43123/workspace").unwrap();
+    let incoming = Url::parse("http://127.0.0.1:43124/workspace").unwrap();
+    let failed = Url::parse("http://127.0.0.1:43125/workspace").unwrap();
+    state.renderer_access.claim("outgoing", &outgoing).unwrap();
+    state
+        .renderer_access
+        .begin_navigation(Some(&incoming))
+        .unwrap();
+
+    let failed_navigation = state
+        .renderer_access
+        .begin_navigation(Some(&failed))
+        .unwrap();
+    state.renderer_access.cancel_navigation(failed_navigation);
+
+    state.renderer_access.claim("incoming", &incoming).unwrap();
+    state
+        .renderer_access
+        .validate("incoming", &incoming)
+        .unwrap();
+}
+#[test]
+fn flush_generation_and_request_order_are_strict() {
+    let directory = tempfile::tempdir().unwrap();
+    let state = Arc::new(ClientState::initialize_at(directory.path()).unwrap());
+    state
+        .renderer_flush
+        .next_generation
+        .store(2, Ordering::SeqCst);
+    state.acknowledge_renderer_flush(1);
+    assert_eq!(acknowledged_generation(&state), 0);
+    state.acknowledge_renderer_flush(2);
+    assert_eq!(acknowledged_generation(&state), 2);
+    let first = state.renderer_flush.request_lock.lock().unwrap();
+    let waiting = Arc::clone(&state);
+    let (sender, receiver) = mpsc::channel();
+    let waiter = thread::spawn(move || {
+        let _request = waiting.renderer_flush.request_lock.lock().unwrap();
+        sender.send(()).unwrap();
+    });
+    assert_receive_timeout(receiver.recv_timeout(Duration::from_millis(20)));
+    drop(first);
+    receiver.recv_timeout(Duration::from_secs(1)).unwrap();
+    waiter.join().unwrap();
+}
+#[test]
+fn ownership_release_drains_active_write_and_blocks_later_writes() {
+    let directory = tempfile::tempdir().unwrap();
+    let (started_tx, started_rx) = mpsc::sync_channel(0);
+    let (allow_tx, allow_rx) = mpsc::sync_channel(0);
+    let allow_rx = std::sync::Mutex::new(allow_rx);
+    let state = Arc::new(
+        ClientState::initialize_at_with_writer(
+            directory.path(),
+            Arc::new(move |path, bytes, ownership_valid| {
+                started_tx.send(()).unwrap();
+                allow_rx.lock().unwrap().recv().unwrap();
+                super::write_atomically(path, bytes, ownership_valid)
+            }),
+        )
+        .unwrap(),
+    );
+    enable_restore_in_memory(&state);
+    let writing = Arc::clone(&state);
+    let writer = thread::spawn(move || writing.save_snapshot(json!({ "first": true })));
+    started_rx.recv().unwrap();
+    let releasing = Arc::clone(&state);
+    let (released_tx, released_rx) = mpsc::channel();
+    let releaser = thread::spawn(move || {
+        releasing.release_locks();
+        released_tx.send(()).unwrap();
+    });
+    assert_receive_timeout(released_rx.recv_timeout(Duration::from_millis(50)));
+    allow_tx.send(()).unwrap();
+    assert!(writer.join().unwrap().unwrap());
+    released_rx.recv().unwrap();
+    releaser.join().unwrap();
+    assert!(!state.is_primary());
+    assert!(!state.save_snapshot(json!({ "tooLate": true })).unwrap());
+}
+
+#[test]
+fn ownership_loss_blocks_the_final_atomic_replacement() {
+    let directory = tempfile::tempdir().unwrap();
+    let owner_path = directory
+        .path()
+        .join(".cross-host-election")
+        .join("primary.owner.json")
+        .join("owner.json");
+    let state = ClientState::initialize_at_with_writer(
+        directory.path(),
+        Arc::new(move |path, bytes, ownership_valid| {
+            fs::write(&owner_path, b"malformed").unwrap();
+            super::write_atomically(path, bytes, ownership_valid)
+        }),
+    )
+    .unwrap();
+    enable_restore_in_memory(&state);
+    assert_eq!(
+        state.save_snapshot(json!({ "blocked": true })).unwrap_err(),
+        "Client state ownership changed before atomic replacement"
+    );
+    assert!(!state.is_primary());
+    assert_eq!(state.load().unwrap(), load(false, true, Value::Null));
+    assert!(!directory.path().join(CLIENT_STATE_FILENAME).exists());
+}
+
+#[test]
+fn renderer_rotation_blocks_an_in_flight_old_renderer_replacement() {
+    let directory = tempfile::tempdir().unwrap();
+    let (started_tx, started_rx) = mpsc::sync_channel(0);
+    let (allow_tx, allow_rx) = mpsc::sync_channel(0);
+    let allow_rx = std::sync::Mutex::new(allow_rx);
+    let state = Arc::new(
+        ClientState::initialize_at_with_writer(
+            directory.path(),
+            Arc::new(move |path, bytes, replacement_valid| {
+                started_tx.send(()).unwrap();
+                allow_rx.lock().unwrap().recv().unwrap();
+                super::write_atomically(path, bytes, replacement_valid)
+            }),
+        )
+        .unwrap(),
+    );
+    enable_restore_in_memory(&state);
+    let outgoing = Url::parse("http://127.0.0.1:43123/workspace").unwrap();
+    let incoming = Url::parse("http://127.0.0.1:43124/workspace").unwrap();
+    state.renderer_access.claim("old", &outgoing).unwrap();
+    let generation = state.renderer_access.validate("old", &outgoing).unwrap();
+    let writing = Arc::clone(&state);
+    let authority = Arc::clone(&state);
+    let writer = thread::spawn(move || {
+        writing.save_snapshot_guarded(json!({ "stale": true }), || {
+            authority.renderer_access.is_generation_current(generation)
+        })
+    });
+    started_rx.recv().unwrap();
+    state
+        .renderer_access
+        .begin_navigation(Some(&incoming))
+        .unwrap();
+    state.renderer_access.claim("new", &incoming).unwrap();
+    allow_tx.send(()).unwrap();
+    assert!(writer.join().unwrap().is_err());
+    assert_eq!(state.load().unwrap().snapshot, Value::Null);
+    assert!(!directory.path().join(CLIENT_STATE_FILENAME).exists());
+}
+#[test]
+fn oversized_snapshot_does_not_replace_state() {
+    let directory = tempfile::tempdir().unwrap();
+    let state = ClientState::initialize_at(directory.path()).unwrap();
+    enable_restore(&state);
+    state.save_snapshot(json!({ "small": true })).unwrap();
+    assert!(state
+        .save_snapshot(Value::String("x".repeat(MAX_CLIENT_SNAPSHOT_BYTES)))
+        .is_err());
+    assert_eq!(state.load().unwrap().snapshot, json!({ "small": true }));
+}
diff --git a/packages/tauri-app/src-tauri/src/client_state/window.rs b/packages/tauri-app/src-tauri/src/client_state/window.rs
new file mode 100644
index 00000000..fbcad4f8
--- /dev/null
+++ b/packages/tauri-app/src-tauri/src/client_state/window.rs
@@ -0,0 +1,379 @@
+use super::ClientState;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::sync::atomic::Ordering;
+use std::time::Duration;
+use tauri::{AppHandle, LogicalPosition, LogicalSize, Manager, WindowEvent};
+
+const MIN_WINDOW_WIDTH: i32 = 800;
+const MIN_WINDOW_HEIGHT: i32 = 600;
+const MIN_ZOOM_LEVEL: f64 = 0.25;
+pub(super) const MAX_ZOOM_LEVEL: f64 = 5.0;
+const SAVE_DEBOUNCE: Duration = Duration::from_millis(250);
+
+pub const DEFAULT_ZOOM_LEVEL: f64 = 1.0;
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct WindowBounds {
+    pub(super) x: i32,
+    pub(super) y: i32,
+    pub(super) width: i32,
+    pub(super) height: i32,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct NativeWindowState {
+    pub(super) bounds: WindowBounds,
+    pub(super) maximized: bool,
+    pub(super) fullscreen: bool,
+    pub(super) zoom_factor: f64,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub(super) struct DisplayArea {
+    pub(super) x: i32,
+    pub(super) y: i32,
+    pub(super) width: u32,
+    pub(super) height: u32,
+}
+
+pub(super) fn normalize_window_state(value: &Value) -> Option<NativeWindowState> {
+    let value = value.as_object()?;
+    let bounds: WindowBounds = serde_json::from_value(value.get("bounds")?.clone()).ok()?;
+    if bounds.width <= 0 || bounds.height <= 0 {
+        return None;
+    }
+
+    Some(NativeWindowState {
+        bounds,
+        maximized: value.get("maximized").and_then(Value::as_bool) == Some(true),
+        fullscreen: value.get("fullscreen").and_then(Value::as_bool) == Some(true),
+        zoom_factor: normalize_zoom_level(value.get("zoomFactor").and_then(Value::as_f64)),
+    })
+}
+
+fn normalize_zoom_level(value: Option<f64>) -> f64 {
+    match value {
+        Some(value) if value.is_finite() && value > 0.0 => {
+            value.clamp(MIN_ZOOM_LEVEL, MAX_ZOOM_LEVEL)
+        }
+        _ => DEFAULT_ZOOM_LEVEL,
+    }
+}
+
+pub(super) fn normalize_native_zoom_level(value: f64) -> Option<f64> {
+    (value.is_finite() && value > 0.0).then(|| normalize_zoom_level(Some(value)))
+}
+
+pub(super) fn clamp_window_bounds(
+    bounds: &WindowBounds,
+    displays: &[DisplayArea],
+) -> Option<WindowBounds> {
+    let display = displays
+        .iter()
+        .copied()
+        .filter(|display| display.width > 0 && display.height > 0)
+        .reduce(|best, candidate| {
+            let best_intersection = intersection_area(bounds, best);
+            let candidate_intersection = intersection_area(bounds, candidate);
+            if candidate_intersection > best_intersection
+                || (candidate_intersection == best_intersection
+                    && center_distance_squared(bounds, candidate)
+                        < center_distance_squared(bounds, best))
+            {
+                candidate
+            } else {
+                best
+            }
+        })?;
+    let maximum_width = display.width.min(i32::MAX as u32) as i32;
+    let maximum_height = display.height.min(i32::MAX as u32) as i32;
+    let width = bounds
+        .width
+        .clamp(MIN_WINDOW_WIDTH.min(maximum_width), maximum_width);
+    let height = bounds
+        .height
+        .clamp(MIN_WINDOW_HEIGHT.min(maximum_height), maximum_height);
+    let minimum_x = i64::from(display.x);
+    let minimum_y = i64::from(display.y);
+    let maximum_x = (minimum_x + i64::from(maximum_width - width)).min(i64::from(i32::MAX));
+    let maximum_y = (minimum_y + i64::from(maximum_height - height)).min(i64::from(i32::MAX));
+
+    Some(WindowBounds {
+        x: i64::from(bounds.x).clamp(minimum_x, maximum_x) as i32,
+        y: i64::from(bounds.y).clamp(minimum_y, maximum_y) as i32,
+        width,
+        height,
+    })
+}
+
+fn intersection_area(bounds: &WindowBounds, display: DisplayArea) -> i64 {
+    let left = i64::from(bounds.x).max(i64::from(display.x));
+    let top = i64::from(bounds.y).max(i64::from(display.y));
+    let right = (i64::from(bounds.x) + i64::from(bounds.width))
+        .min(i64::from(display.x) + i64::from(display.width));
+    let bottom = (i64::from(bounds.y) + i64::from(bounds.height))
+        .min(i64::from(display.y) + i64::from(display.height));
+    (right - left).max(0) * (bottom - top).max(0)
+}
+
+fn center_distance_squared(bounds: &WindowBounds, display: DisplayArea) -> i128 {
+    let bounds_x = i128::from(bounds.x) * 2 + i128::from(bounds.width);
+    let bounds_y = i128::from(bounds.y) * 2 + i128::from(bounds.height);
+    let display_x = i128::from(display.x) * 2 + i128::from(display.width);
+    let display_y = i128::from(display.y) * 2 + i128::from(display.height);
+    (bounds_x - display_x).pow(2) + (bounds_y - display_y).pow(2)
+}
+
+fn capture_main_window_in_memory(app: &AppHandle) {
+    let Some(client_state) = app.try_state::<ClientState>() else {
+        return;
+    };
+    let Ok(_write) = client_state.write_lock.lock() else {
+        return;
+    };
+    if !client_state.is_primary() {
+        return;
+    }
+    if client_state.normal_writes_suppressed().unwrap_or(true) {
+        return;
+    }
+    let Some(window) = app.get_webview_window("main") else {
+        return;
+    };
+
+    let maximized = window.is_maximized().unwrap_or(false);
+    let fullscreen = window.is_fullscreen().unwrap_or(false);
+    let minimized = window.is_minimized().unwrap_or(false);
+    let scale_factor = window.scale_factor().unwrap_or(1.0);
+    let current_bounds = if !maximized && !fullscreen && !minimized {
+        window
+            .outer_position()
+            .ok()
+            .zip(window.inner_size().ok())
+            .and_then(|(position, size)| {
+                let position = position.to_logical::<i32>(scale_factor);
+                let size = size.to_logical::<u32>(scale_factor);
+                let bounds = WindowBounds {
+                    x: position.x,
+                    y: position.y,
+                    width: size.width.min(i32::MAX as u32) as i32,
+                    height: size.height.min(i32::MAX as u32) as i32,
+                };
+                (bounds.width > 0 && bounds.height > 0).then_some(bounds)
+            })
+    } else {
+        None
+    };
+    let zoom_factor = client_state
+        .zoom_level
+        .lock()
+        .map(|zoom| *zoom)
+        .unwrap_or(DEFAULT_ZOOM_LEVEL);
+    let Ok(mut state) = client_state.state.lock() else {
+        return;
+    };
+    let bounds =
+        current_bounds.or_else(|| state.window.as_ref().map(|window| window.bounds.clone()));
+    if let Some(bounds) = bounds {
+        state.window = Some(NativeWindowState {
+            bounds,
+            maximized,
+            fullscreen,
+            zoom_factor,
+        });
+    }
+}
+
+fn schedule_flush(app: &AppHandle) {
+    let Some(client_state) = app.try_state::<ClientState>() else {
+        return;
+    };
+    let generation = client_state.save_generation.fetch_add(1, Ordering::SeqCst) + 1;
+    let app = app.clone();
+    std::thread::spawn(move || {
+        std::thread::sleep(SAVE_DEBOUNCE);
+        let Some(client_state) = app.try_state::<ClientState>() else {
+            return;
+        };
+        if client_state.save_generation.load(Ordering::SeqCst) == generation {
+            if let Err(err) = client_state.flush() {
+                eprintln!("[client-state] failed to save window state: {err}");
+            }
+        }
+    });
+}
+
+#[cfg(windows)]
+fn register_native_zoom_handler(window: &tauri::WebviewWindow, app: &AppHandle) {
+    use webview2_com::ZoomFactorChangedEventHandler;
+
+    let app = app.clone();
+    if let Err(err) = window.with_webview(move |webview| {
+        let controller = webview.controller();
+        let callback_app = app.clone();
+        let handler = ZoomFactorChangedEventHandler::create(Box::new(move |sender, _| {
+            let Some(controller) = sender else {
+                return Ok(());
+            };
+            let mut native_zoom = 0.0;
+            if let Err(err) = unsafe { controller.ZoomFactor(&mut native_zoom) } {
+                eprintln!("[client-state] failed to read native zoom level: {err}");
+                return Ok(());
+            }
+            let Some(normalized) = normalize_native_zoom_level(native_zoom) else {
+                eprintln!("[client-state] ignored invalid native zoom level: {native_zoom}");
+                return Ok(());
+            };
+            let Some(client_state) = callback_app.try_state::<ClientState>() else {
+                return Ok(());
+            };
+            let Ok(mut zoom_level) = client_state.zoom_level.lock() else {
+                return Ok(());
+            };
+            *zoom_level = normalized;
+            drop(zoom_level);
+
+            if client_state.is_primary()
+                && client_state.normal_writes_suppressed().ok() == Some(false)
+            {
+                capture_main_window_in_memory(&callback_app);
+                schedule_flush(&callback_app);
+            }
+            Ok(())
+        }));
+        let mut token = 0;
+        if let Err(err) = unsafe { controller.add_ZoomFactorChanged(&handler, &mut token) } {
+            eprintln!("[client-state] failed to register native zoom handler: {err}");
+        }
+    }) {
+        eprintln!("[client-state] failed to access native webview for zoom tracking: {err}");
+    }
+}
+
+pub fn setup_main_window(app: &AppHandle) -> Result<(), String> {
+    let client_state = app.state::<ClientState>();
+    let window = app
+        .get_webview_window("main")
+        .ok_or_else(|| "main window was not created".to_string())?;
+    let initial_zoom = client_state
+        .zoom_level
+        .lock()
+        .map(|zoom| *zoom)
+        .unwrap_or(DEFAULT_ZOOM_LEVEL);
+    let _ = window.set_zoom(initial_zoom);
+    #[cfg(windows)]
+    register_native_zoom_handler(&window, app);
+    if !client_state.is_primary() {
+        let _ = window.show();
+        return Ok(());
+    }
+
+    let saved_window = {
+        let state = client_state.state.lock().map_err(|err| err.to_string())?;
+        state
+            .restore_enabled
+            .then(|| state.window.clone())
+            .flatten()
+    };
+    if let Some(mut saved_window) = saved_window {
+        let startup_scale = window.scale_factor().unwrap_or(1.0);
+        let displays = window
+            .available_monitors()
+            .unwrap_or_default()
+            .into_iter()
+            .map(|monitor| {
+                let work_area = monitor.work_area();
+                let position = work_area.position.to_logical::<i32>(startup_scale);
+                let size = work_area.size.to_logical::<u32>(startup_scale);
+                DisplayArea {
+                    x: position.x,
+                    y: position.y,
+                    width: size.width,
+                    height: size.height,
+                }
+            })
+            .collect::<Vec<_>>();
+        if let Some(bounds) = clamp_window_bounds(&saved_window.bounds, &displays) {
+            let _ = window.set_size(LogicalSize::new(bounds.width as u32, bounds.height as u32));
+            let _ = window.set_position(LogicalPosition::new(bounds.x, bounds.y));
+            saved_window.bounds = bounds;
+        } else if let Ok(position) = window.outer_position() {
+            if let Ok(size) = window.inner_size() {
+                let scale_factor = window.scale_factor().unwrap_or(1.0);
+                let position = position.to_logical::<i32>(scale_factor);
+                let size = size.to_logical::<u32>(scale_factor);
+                saved_window.bounds = WindowBounds {
+                    x: position.x,
+                    y: position.y,
+                    width: size.width.min(i32::MAX as u32) as i32,
+                    height: size.height.min(i32::MAX as u32) as i32,
+                };
+            }
+        }
+        if let Ok(mut state) = client_state.state.lock() {
+            state.window = Some(saved_window.clone());
+        }
+        let _ = window.set_zoom(saved_window.zoom_factor);
+        if saved_window.maximized {
+            let _ = window.maximize();
+        }
+        if saved_window.fullscreen {
+            let _ = window.set_fullscreen(true);
+            if cfg!(not(target_os = "macos")) {
+                let _ = window.hide_menu();
+            }
+        }
+    }
+
+    capture_main_window_in_memory(app);
+    let app_handle = app.clone();
+    window.on_window_event(move |event| match event {
+        WindowEvent::Resized(_)
+        | WindowEvent::Moved(_)
+        | WindowEvent::ScaleFactorChanged { .. } => {
+            capture_main_window_in_memory(&app_handle);
+            schedule_flush(&app_handle);
+        }
+        _ => {}
+    });
+    let _ = window.show();
+    Ok(())
+}
+
+pub fn set_main_window_zoom(app: &AppHandle, next_zoom: f64) {
+    let Some(window) = app.get_webview_window("main") else {
+        return;
+    };
+    let normalized = normalize_zoom_level(Some(next_zoom));
+    if window.set_zoom(normalized).is_err() {
+        return;
+    }
+    let Some(client_state) = app.try_state::<ClientState>() else {
+        return;
+    };
+    if let Ok(mut zoom_level) = client_state.zoom_level.lock() {
+        *zoom_level = normalized;
+    }
+    capture_main_window_in_memory(app);
+    if let Err(err) = client_state.flush() {
+        eprintln!("[client-state] failed to save zoom level: {err}");
+    }
+}
+
+pub fn main_window_zoom(app: &AppHandle) -> f64 {
+    app.try_state::<ClientState>()
+        .and_then(|state| state.zoom_level.lock().ok().map(|zoom| *zoom))
+        .unwrap_or(DEFAULT_ZOOM_LEVEL)
+}
+
+pub fn capture_and_flush_main_window(app: &AppHandle) {
+    capture_main_window_in_memory(app);
+    if let Some(state) = app.try_state::<ClientState>() {
+        if let Err(err) = state.flush() {
+            eprintln!("[client-state] failed to flush main window state: {err}");
+        }
+    }
+}
diff --git a/packages/tauri-app/src-tauri/src/linux_tls.rs b/packages/tauri-app/src-tauri/src/linux_tls.rs
index 1a4865d2..6228d079 100644
--- a/packages/tauri-app/src-tauri/src/linux_tls.rs
+++ b/packages/tauri-app/src-tauri/src/linux_tls.rs
@@ -30,15 +30,17 @@ pub fn ensure_remote_window_tls_handler(
             let webview = platform_webview.inner();
             let app_handle = app_handle.clone();
             let window_label = window_label.clone();
-            webview.connect_load_failed_with_tls_errors(move |view, failing_uri, certificate, _| {
-                allow_remote_tls_certificate(
-                    &app_handle,
-                    &window_label,
-                    view,
-                    failing_uri,
-                    certificate,
-                )
-            });
+            webview.connect_load_failed_with_tls_errors(
+                move |view, failing_uri, certificate, _| {
+                    allow_remote_tls_certificate(
+                        &app_handle,
+                        &window_label,
+                        view,
+                        failing_uri,
+                        certificate,
+                    )
+                },
+            );
         })
         .map_err(|err| err.to_string())
 }
diff --git a/packages/tauri-app/src-tauri/src/main.rs b/packages/tauri-app/src-tauri/src/main.rs
index 7ad5d7c2..5764c1b5 100644
--- a/packages/tauri-app/src-tauri/src/main.rs
+++ b/packages/tauri-app/src-tauri/src/main.rs
@@ -3,21 +3,27 @@
 #[allow(dead_code)]
 mod cert_manager;
 mod cli_manager;
+mod client_state;
 mod desktop_event_transport;
 #[cfg(target_os = "linux")]
 mod linux_tls;
 mod managed_node;
+mod shutdown;
+mod windows_update;
 
 use cli_manager::{CliProcessManager, CliStatus};
-use desktop_event_transport::{DesktopEventTransportManager, DesktopEventsStartRequest, DesktopEventsStartResult};
+use desktop_event_transport::{
+    DesktopEventTransportManager, DesktopEventsStartRequest, DesktopEventsStartResult,
+};
 use keepawake::KeepAwake;
 use serde::Deserialize;
 use serde_json::json;
 use std::collections::{HashMap, HashSet};
-use std::sync::atomic::{AtomicBool, Ordering};
+#[cfg(any(windows, test))]
+use std::future::Future;
 use std::sync::Mutex;
 use std::time::{SystemTime, UNIX_EPOCH};
-use tauri::menu::{MenuBuilder, MenuItem, SubmenuBuilder};
+use tauri::menu::{AboutMetadata, MenuBuilder, MenuItem, PredefinedMenuItem, SubmenuBuilder};
 use tauri::plugin::{Builder as PluginBuilder, TauriPlugin};
 use tauri::webview::{PageLoadEvent, Webview};
 use tauri::{
@@ -38,11 +44,8 @@ use std::os::windows::ffi::OsStrExt;
 #[cfg(windows)]
 use windows_sys::Win32::UI::Shell::SetCurrentProcessExplicitAppUserModelID;
 
-static QUIT_REQUESTED: AtomicBool = AtomicBool::new(false);
-const DEFAULT_ZOOM_LEVEL: f64 = 1.0;
 const ZOOM_STEP: f64 = 0.1;
-const MIN_ZOOM_LEVEL: f64 = 0.2;
-const MAX_ZOOM_LEVEL: f64 = 5.0;
+const RELEASES_URL: &str = "https://github.com/NeuralNomadsAI/CodeNomad/releases/latest";
 const LOCAL_WINDOW_CONTEXT_SCRIPT: &str = "window.__CODENOMAD_WINDOW_CONTEXT__ = 'local';";
 const REMOTE_WINDOW_CONTEXT_SCRIPT: &str = "window.__CODENOMAD_WINDOW_CONTEXT__ = 'remote';";
 
@@ -53,7 +56,6 @@ pub struct AppState {
     pub manager: CliProcessManager,
     pub desktop_events: DesktopEventTransportManager,
     pub wake_lock: Mutex<Option<KeepAwake>>,
-    pub zoom_level: Mutex<f64>,
     pub remote_origins: Mutex<HashMap<String, String>>,
     pub remote_proxy_sessions: Mutex<HashMap<String, String>>,
     pub remote_skip_tls_verify: Mutex<HashMap<String, bool>>,
@@ -350,6 +352,9 @@ async fn open_remote_window_impl(
     .build()
     .map_err(|err| err.to_string())?;
 
+    #[cfg(windows)]
+    shutdown::schedule_windows_session_end_handler(&window)?;
+
     #[cfg(target_os = "linux")]
     {
         linux_tls::ensure_remote_window_tls_handler(&window, &app, &label)?;
@@ -462,59 +467,65 @@ fn emit_folder_drop_event(
     }
 }
 
-fn clamp_zoom_level(value: f64) -> f64 {
-    value.clamp(MIN_ZOOM_LEVEL, MAX_ZOOM_LEVEL)
-}
-
-fn set_main_window_zoom(app_handle: &AppHandle, next_zoom: f64) {
-    if let Some(window) = app_handle.get_webview_window("main") {
-        let normalized = clamp_zoom_level(next_zoom);
-        if window.set_zoom(normalized).is_ok() {
-            if let Ok(mut zoom_level) = app_handle.state::<AppState>().zoom_level.lock() {
-                *zoom_level = normalized;
-            }
-        }
-    }
-}
-
 fn reload_main_window(app_handle: &AppHandle) {
-    if let Some(window) = app_handle.get_webview_window("main") {
-        let _ = window.reload();
-    }
+    client_state::before_main_window_navigation(
+        app_handle,
+        client_state::NavigationKind::Reload,
+        None,
+        |app| {
+            let window = app
+                .get_webview_window("main")
+                .ok_or_else(|| "main window not found for reload".to_string())?;
+            window
+                .reload()
+                .map_err(|err| format!("failed to reload main window: {err}"))
+        },
+    );
 }
 
 fn force_reload_main_window(app_handle: &AppHandle) {
-    if let Some(window) = app_handle.get_webview_window("main") {
-        if let Ok(mut url) = window.url() {
-            if should_allow_internal(&url) {
-                let reload_token = SystemTime::now()
-                    .duration_since(UNIX_EPOCH)
-                    .unwrap_or_default()
-                    .as_millis()
-                    .to_string();
+    client_state::before_main_window_navigation(
+        app_handle,
+        client_state::NavigationKind::ForceReload,
+        None,
+        |app| {
+            let window = app
+                .get_webview_window("main")
+                .ok_or_else(|| "main window not found for force reload".to_string())?;
+            if let Ok(mut url) = window.url() {
+                if should_allow_internal(&url) {
+                    let reload_token = SystemTime::now()
+                        .duration_since(UNIX_EPOCH)
+                        .unwrap_or_default()
+                        .as_millis()
+                        .to_string();
 
-                let existing_pairs: Vec<(String, String)> = url
-                    .query_pairs()
-                    .into_owned()
-                    .filter(|(key, _)| key != "__codenomad_force_reload")
-                    .collect();
+                    let existing_pairs: Vec<(String, String)> = url
+                        .query_pairs()
+                        .into_owned()
+                        .filter(|(key, _)| key != "__codenomad_force_reload")
+                        .collect();
 
-                {
-                    let mut pairs = url.query_pairs_mut();
-                    pairs.clear();
-                    for (key, value) in existing_pairs {
-                        pairs.append_pair(&key, &value);
+                    {
+                        let mut pairs = url.query_pairs_mut();
+                        pairs.clear();
+                        for (key, value) in existing_pairs {
+                            pairs.append_pair(&key, &value);
+                        }
+                        pairs.append_pair("__codenomad_force_reload", &reload_token);
                     }
-                    pairs.append_pair("__codenomad_force_reload", &reload_token);
+
+                    return window
+                        .navigate(url)
+                        .map_err(|err| format!("failed to force reload main window: {err}"));
                 }
-
-                let _ = window.navigate(url);
-                return;
             }
-        }
 
-        let _ = window.reload();
-    }
+            window
+                .reload()
+                .map_err(|err| format!("failed to force reload main window: {err}"))
+        },
+    );
 }
 
 fn toggle_fullscreen_window(app_handle: &AppHandle) {
@@ -556,6 +567,11 @@ fn set_windows_app_user_model_id() {
 fn set_windows_app_user_model_id() {}
 
 fn main() {
+    #[cfg(windows)]
+    if let Some(code) = cli_manager::run_windows_cli_launcher_if_requested() {
+        std::process::exit(code);
+    }
+
     let _ = rustls::crypto::ring::default_provider().install_default();
 
     let navigation_guard: TauriPlugin<Wry, ()> = PluginBuilder::new("external-link-guard")
@@ -584,7 +600,6 @@ fn main() {
             manager: CliProcessManager::new(),
             desktop_events: DesktopEventTransportManager::new(),
             wake_lock: Mutex::new(None),
-            zoom_level: Mutex::new(DEFAULT_ZOOM_LEVEL),
             remote_origins: Mutex::new(HashMap::new()),
             remote_proxy_sessions: Mutex::new(HashMap::new()),
             remote_skip_tls_verify: Mutex::new(HashMap::new()),
@@ -601,8 +616,16 @@ fn main() {
         })
         .setup(|app| {
             set_windows_app_user_model_id();
+            let client_state = client_state::ClientState::initialize(&app.handle());
+            app.manage(client_state);
+            app.manage(shutdown::ShutdownCoordinator::default());
             build_menu(&app.handle())?;
+            client_state::setup_main_window(&app.handle())
+                .map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err))?;
             if let Some(window) = app.get_webview_window("main") {
+                #[cfg(windows)]
+                shutdown::install_windows_session_end_handler(&window)
+                    .map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err))?;
                 let _ = window.eval(LOCAL_WINDOW_CONTEXT_SCRIPT);
             }
             if let Some(shortcut) = fullscreen_shortcut() {
@@ -642,7 +665,15 @@ fn main() {
             wake_lock_start,
             wake_lock_stop,
             needs_local_certificate_install,
-            open_remote_window
+            open_remote_window,
+            client_state::client_state_claim_access,
+            client_state::client_state_load,
+            client_state::client_state_save,
+            client_state::client_state_set_restore_enabled,
+            client_state::client_state_clear,
+            client_state::client_state_renderer_flushed,
+            client_state::client_state_navigation_flushed,
+            windows_update::install_stable_update
         ])
         .on_menu_event(|app_handle, event| {
             match event.id().0.as_str() {
@@ -673,17 +704,18 @@ fn main() {
                     }
                 }
                 "reset_zoom" => {
-                    set_main_window_zoom(app_handle, DEFAULT_ZOOM_LEVEL);
+                    client_state::set_main_window_zoom(
+                        app_handle,
+                        client_state::DEFAULT_ZOOM_LEVEL,
+                    );
                 }
                 "zoom_in" => {
-                    if let Ok(zoom_level) = app_handle.state::<AppState>().zoom_level.lock() {
-                        set_main_window_zoom(app_handle, *zoom_level + ZOOM_STEP);
-                    }
+                    let zoom_level = client_state::main_window_zoom(app_handle);
+                    client_state::set_main_window_zoom(app_handle, zoom_level + ZOOM_STEP);
                 }
                 "zoom_out" => {
-                    if let Ok(zoom_level) = app_handle.state::<AppState>().zoom_level.lock() {
-                        set_main_window_zoom(app_handle, *zoom_level - ZOOM_STEP);
-                    }
+                    let zoom_level = client_state::main_window_zoom(app_handle);
+                    client_state::set_main_window_zoom(app_handle, zoom_level - ZOOM_STEP);
                 }
 
                 "toggle_fullscreen" => {
@@ -707,11 +739,20 @@ fn main() {
                     }
                 }
 
-                // App menu (macOS)
-                "about" => {
-                    // TODO: Implement about dialog
-                    println!("About menu item clicked");
+                "get_updates" => {
+                    #[cfg(windows)]
+                    {
+                        let app_handle = app_handle.clone();
+                        tauri::async_runtime::spawn(run_update_with_fallback(
+                            windows_update::install_stable_update(),
+                            move || open_releases_page(&app_handle),
+                        ));
+                    }
+
+                    #[cfg(not(windows))]
+                    open_releases_page(app_handle);
                 }
+                // App menu (macOS)
                 "hide" => {
                     if let Some(window) = app_handle.get_webview_window("main") {
                         let _ = window.hide();
@@ -735,20 +776,11 @@ fn main() {
         .expect("error while building tauri application")
         .run(|app_handle, event| match event {
             tauri::RunEvent::ExitRequested { api, .. } => {
-                // `app_handle.exit(0)` triggers another `ExitRequested`. Without a guard, we can
-                // prevent exit forever and the app never quits (Cmd+Q / Quit menu appears stuck).
-                if QUIT_REQUESTED.swap(true, Ordering::SeqCst) {
+                if shutdown::exit_allowed(&app_handle) {
                     return;
                 }
                 api.prevent_exit();
-                let app = app_handle.clone();
-                std::thread::spawn(move || {
-                    if let Some(state) = app.try_state::<AppState>() {
-                        state.desktop_events.stop();
-                        let _ = state.manager.stop();
-                    }
-                    app.exit(0);
-                });
+                shutdown::request(app_handle.clone());
             }
             tauri::RunEvent::WindowEvent {
                 label,
@@ -772,35 +804,44 @@ fn main() {
                 emit_window_event(&app_handle, &label, "desktop:folder-drag-leave");
             }
             tauri::RunEvent::WindowEvent {
+                label,
                 event: tauri::WindowEvent::CloseRequested { api, .. },
                 ..
             } => {
+                if label == "main" {
+                    if shutdown::main_window_close_allowed(&app_handle) {
+                        return;
+                    }
+                    let final_window = app_handle.webview_windows().len() == 1;
+                    if shutdown::exit_allowed(&app_handle) {
+                        return;
+                    }
+                    api.prevent_close();
+                    if final_window {
+                        shutdown::request(app_handle.clone());
+                    } else {
+                        shutdown::request_main_window_close(app_handle.clone());
+                    }
+                    return;
+                }
                 // Let windows close normally. App shutdown is handled only after the
                 // last window is actually gone so remote windows can outlive `main`.
-                let _ = api;
             }
             tauri::RunEvent::WindowEvent {
+                label,
                 event: tauri::WindowEvent::Destroyed,
                 ..
             } => {
+                if label == "main" {
+                    shutdown::main_window_destroyed(app_handle.clone());
+                }
                 if !app_handle.webview_windows().is_empty() {
                     return;
                 }
 
                 // Stop the CLI only when the final window is gone and the app is
                 // truly exiting.
-                if QUIT_REQUESTED.swap(true, Ordering::SeqCst) {
-                    return;
-                }
-
-                let app = app_handle.clone();
-                std::thread::spawn(move || {
-                    if let Some(state) = app.try_state::<AppState>() {
-                        state.desktop_events.stop();
-                        let _ = state.manager.stop();
-                    }
-                    app.exit(0);
-                });
+                shutdown::request(app_handle.clone());
             }
             _ => {}
         });
@@ -812,11 +853,27 @@ fn build_menu(app: &AppHandle) -> tauri::Result<()> {
 
     // Create submenus
     let mut submenus = Vec::new();
+    let about_item = PredefinedMenuItem::about(
+        app,
+        Some("About CodeNomad"),
+        Some(build_about_metadata(
+            &app.package_info().version.to_string(),
+            cfg!(target_os = "linux"),
+        )),
+    )?;
+    let get_updates_item = MenuItem::with_id(
+        app,
+        "get_updates",
+        "Get Updates...",
+        true,
+        None::<&str>,
+    )?;
 
     // App menu (macOS only)
     if is_mac {
         let app_menu = SubmenuBuilder::new(app, "CodeNomad")
-            .text("about", "About CodeNomad")
+            .item(&about_item)
+            .item(&get_updates_item)
             .separator()
             .text("hide", "Hide CodeNomad")
             .text("hide_others", "Hide Others")
@@ -954,6 +1011,15 @@ fn build_menu(app: &AppHandle) -> tauri::Result<()> {
     };
     submenus.push(window_menu);
 
+    if !is_mac {
+        let help_menu = SubmenuBuilder::new(app, "Help")
+            .item(&get_updates_item)
+            .separator()
+            .item(&about_item)
+            .build()?;
+        submenus.push(help_menu);
+    }
+
     // Build the main menu with all submenus
     let submenu_refs: Vec<&dyn tauri::menu::IsMenuItem<_>> = submenus
         .iter()
@@ -964,3 +1030,69 @@ fn build_menu(app: &AppHandle) -> tauri::Result<()> {
     app.set_menu(menu)?;
     Ok(())
 }
+
+#[cfg(any(windows, test))]
+async fn run_update_with_fallback(
+    update: impl Future<Output = Result<(), String>>,
+    fallback: impl FnOnce(),
+) {
+    if let Err(err) = update.await {
+        eprintln!("[tauri] WinGet update failed, opening the releases page: {err}");
+        fallback();
+    }
+}
+
+fn open_releases_page(app_handle: &AppHandle) {
+    if let Err(err) = app_handle.opener().open_url(RELEASES_URL, None::<&str>) {
+        eprintln!("[tauri] failed to open the CodeNomad releases page: {err}");
+    }
+}
+
+fn build_about_metadata(version: &str, include_update_link: bool) -> AboutMetadata<'static> {
+    AboutMetadata {
+        name: Some("CodeNomad".to_string()),
+        version: Some(version.to_string()),
+        authors: Some(vec!["Neural Nomads AI".to_string()]),
+        comments: Some("A desktop workspace for OpenCode.".to_string()),
+        license: Some("MIT".to_string()),
+        website: include_update_link.then(|| RELEASES_URL.to_string()),
+        website_label: include_update_link.then(|| "Get updates".to_string()),
+        ..Default::default()
+    }
+}
+
+#[cfg(test)]
+mod menu_tests {
+    use super::{build_about_metadata, run_update_with_fallback, RELEASES_URL};
+    use std::sync::atomic::{AtomicBool, Ordering};
+
+    #[test]
+    fn failed_update_uses_release_fallback() {
+        let fallback_called = AtomicBool::new(false);
+
+        tauri::async_runtime::block_on(run_update_with_fallback(
+            async { Err("update failed".to_string()) },
+            || fallback_called.store(true, Ordering::Relaxed),
+        ));
+
+        assert!(fallback_called.load(Ordering::Relaxed));
+    }
+
+    #[test]
+    fn about_metadata_includes_version_and_supported_update_link() {
+        let metadata = build_about_metadata("1.2.3", true);
+
+        assert_eq!(metadata.name.as_deref(), Some("CodeNomad"));
+        assert_eq!(metadata.version.as_deref(), Some("1.2.3"));
+        assert_eq!(metadata.website.as_deref(), Some(RELEASES_URL));
+        assert_eq!(metadata.website_label.as_deref(), Some("Get updates"));
+    }
+
+    #[test]
+    fn about_metadata_omits_unsupported_update_link() {
+        let metadata = build_about_metadata("1.2.3", false);
+
+        assert_eq!(metadata.website, None);
+        assert_eq!(metadata.website_label, None);
+    }
+}
diff --git a/packages/tauri-app/src-tauri/src/shutdown.rs b/packages/tauri-app/src-tauri/src/shutdown.rs
new file mode 100644
index 00000000..8fab8fae
--- /dev/null
+++ b/packages/tauri-app/src-tauri/src/shutdown.rs
@@ -0,0 +1,611 @@
+use crate::{client_state, AppState};
+#[cfg(windows)]
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Mutex;
+use std::time::Duration;
+#[cfg(windows)]
+use tauri::WebviewWindow;
+use tauri::{AppHandle, Emitter, Manager};
+
+const RENDERER_FLUSH_TIMEOUT: Duration = Duration::from_secs(1);
+const SHUTDOWN_STOP_ATTEMPTS: usize = 2;
+#[cfg(windows)]
+const WINDOWS_SESSION_END_TIMEOUT: Duration = Duration::from_secs(5);
+
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub(crate) enum ShutdownPhase {
+    #[default]
+    Idle,
+    WaitingForShutdownRenderer,
+    CleanupInProgress,
+    CleanupBlocked,
+    ExitAllowed,
+    WaitingForMainWindowRenderer,
+    FlushingMainWindow,
+    FlushingMainWindowForShutdown,
+    MainWindowCloseAllowed,
+}
+
+#[derive(Default)]
+pub(crate) struct ShutdownCoordinator {
+    state: Mutex<ShutdownState>,
+    #[cfg(windows)]
+    windows_session_end_started: AtomicBool,
+}
+
+#[derive(Default)]
+struct ShutdownState {
+    phase: ShutdownPhase,
+    flush_generation: u64,
+    active_flush_generation: Option<u64>,
+}
+
+impl ShutdownCoordinator {
+    fn apply(&self, event: ShutdownEvent) -> (ShutdownAction, Option<u64>) {
+        let mut state = self.state.lock().unwrap_or_else(|err| err.into_inner());
+        if let Some(generation) = event.renderer_generation() {
+            if state.active_flush_generation != Some(generation) {
+                return (ShutdownAction::None, None);
+            }
+        }
+        let (next, action) = transition(state.phase, event);
+        state.phase = next;
+        if action == ShutdownAction::RequestRendererFlush {
+            state.flush_generation += 1;
+            state.active_flush_generation = Some(state.flush_generation);
+        } else if !matches!(
+            next,
+            ShutdownPhase::WaitingForShutdownRenderer | ShutdownPhase::WaitingForMainWindowRenderer
+        ) {
+            state.active_flush_generation = None;
+        }
+        (action, state.active_flush_generation)
+    }
+
+    fn phase(&self) -> ShutdownPhase {
+        self.state
+            .lock()
+            .unwrap_or_else(|err| err.into_inner())
+            .phase
+    }
+
+    fn with_navigation<T>(&self, operation: impl FnOnce() -> T) -> Option<T> {
+        let state = self.state.lock().unwrap_or_else(|err| err.into_inner());
+        (state.phase == ShutdownPhase::Idle).then(operation)
+    }
+
+    #[cfg(windows)]
+    fn begin_windows_session_end(&self) -> bool {
+        !self
+            .windows_session_end_started
+            .swap(true, Ordering::SeqCst)
+    }
+
+    #[cfg(windows)]
+    fn complete_windows_session_end(&self) {
+        let mut state = self.state.lock().unwrap_or_else(|err| err.into_inner());
+        state.phase = ShutdownPhase::ExitAllowed;
+        state.active_flush_generation = None;
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum ShutdownEvent {
+    BeginShutdown,
+    BeginMainWindowClose,
+    RendererFlushed(u64),
+    RendererUnavailable,
+    RendererTimeout(u64),
+    MainWindowFlushed,
+    MainWindowCloseFailed,
+    MainWindowDestroyed,
+    CleanupFinished,
+    CleanupFailed,
+}
+
+impl ShutdownEvent {
+    fn renderer_generation(self) -> Option<u64> {
+        match self {
+            Self::RendererFlushed(generation) | Self::RendererTimeout(generation) => {
+                Some(generation)
+            }
+            _ => None,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum ShutdownAction {
+    None,
+    RequestRendererFlush,
+    FlushMainWindow,
+    CloseMainWindow,
+    StartCleanup,
+}
+
+fn transition(phase: ShutdownPhase, event: ShutdownEvent) -> (ShutdownPhase, ShutdownAction) {
+    use ShutdownAction::*;
+    use ShutdownEvent::*;
+    use ShutdownPhase::*;
+
+    match (phase, event) {
+        (Idle, BeginShutdown) => (WaitingForShutdownRenderer, RequestRendererFlush),
+        (
+            WaitingForShutdownRenderer,
+            RendererFlushed(_) | RendererUnavailable | RendererTimeout(_) | MainWindowDestroyed,
+        ) => (CleanupInProgress, StartCleanup),
+        (Idle, BeginMainWindowClose) => (WaitingForMainWindowRenderer, RequestRendererFlush),
+        (WaitingForMainWindowRenderer, RendererFlushed(_) | RendererTimeout(_)) => {
+            (FlushingMainWindow, FlushMainWindow)
+        }
+        (WaitingForMainWindowRenderer, RendererUnavailable | MainWindowDestroyed) => (Idle, None),
+        (WaitingForMainWindowRenderer, BeginShutdown) => (WaitingForShutdownRenderer, None),
+        (FlushingMainWindow, BeginShutdown) => (FlushingMainWindowForShutdown, None),
+        (FlushingMainWindow, MainWindowFlushed) => (MainWindowCloseAllowed, CloseMainWindow),
+        (FlushingMainWindow, MainWindowDestroyed) => (Idle, None),
+        (FlushingMainWindowForShutdown, MainWindowFlushed | MainWindowDestroyed) => {
+            (CleanupInProgress, StartCleanup)
+        }
+        (MainWindowCloseAllowed, MainWindowDestroyed | MainWindowCloseFailed) => (Idle, None),
+        (MainWindowCloseAllowed, BeginShutdown) => (CleanupInProgress, StartCleanup),
+        (CleanupInProgress, CleanupFinished) => (ExitAllowed, None),
+        (CleanupInProgress, CleanupFailed) => (CleanupBlocked, None),
+        (CleanupBlocked, BeginShutdown) => (CleanupInProgress, StartCleanup),
+        _ => (phase, None),
+    }
+}
+
+fn apply_event(app: AppHandle, event: ShutdownEvent) {
+    let (action, generation) = app.state::<ShutdownCoordinator>().apply(event);
+
+    match action {
+        ShutdownAction::RequestRendererFlush => request_renderer_flush(app, generation.unwrap()),
+        ShutdownAction::FlushMainWindow => flush_main_window(app),
+        ShutdownAction::CloseMainWindow => close_main_window(app),
+        ShutdownAction::StartCleanup => start_cleanup(app),
+        ShutdownAction::None => {}
+    }
+}
+
+fn request_renderer_flush(app: AppHandle, generation: u64) {
+    let Some(window) = app.get_webview_window("main") else {
+        apply_event(app, ShutdownEvent::RendererUnavailable);
+        return;
+    };
+    if let Err(err) = window.emit(
+        "client-state:flush-requested",
+        client_state::RendererFlushRequest { generation },
+    ) {
+        eprintln!("[client-state] failed to request renderer shutdown flush: {err}");
+    }
+    std::thread::spawn(move || {
+        std::thread::sleep(RENDERER_FLUSH_TIMEOUT);
+        apply_event(app, ShutdownEvent::RendererTimeout(generation));
+    });
+}
+
+fn flush_main_window(app: AppHandle) {
+    std::thread::spawn(move || {
+        client_state::capture_and_flush_main_window(&app);
+        apply_event(app, ShutdownEvent::MainWindowFlushed);
+    });
+}
+
+fn close_main_window(app: AppHandle) {
+    let Some(window) = app.get_webview_window("main") else {
+        apply_event(app, ShutdownEvent::MainWindowDestroyed);
+        return;
+    };
+    if let Err(err) = window.close() {
+        eprintln!("[client-state] failed to close main window after state flush: {err}");
+        apply_event(app, ShutdownEvent::MainWindowCloseFailed);
+    }
+}
+
+fn start_cleanup(app: AppHandle) {
+    std::thread::spawn(move || {
+        let result = cleanup(&app, true);
+        match result {
+            Ok(()) => {
+                apply_event(app.clone(), ShutdownEvent::CleanupFinished);
+                app.exit(0);
+            }
+            Err(err) => {
+                eprintln!(
+                    "[tauri] shutdown cleanup remains unconfirmed after {SHUTDOWN_STOP_ATTEMPTS} attempts: {err}; keeping the app alive for a later quit retry"
+                );
+                apply_event(app, ShutdownEvent::CleanupFailed);
+            }
+        }
+    });
+}
+
+fn retry_bounded<E>(
+    attempts: usize,
+    mut operation: impl FnMut() -> Result<(), E>,
+) -> Result<(), E> {
+    assert!(attempts > 0);
+    for attempt in 1..=attempts {
+        match operation() {
+            Ok(()) => return Ok(()),
+            Err(err) if attempt == attempts => return Err(err),
+            Err(_) => {}
+        }
+    }
+    unreachable!()
+}
+
+fn cleanup(app: &AppHandle, capture_window: bool) -> Result<(), String> {
+    if capture_window {
+        client_state::capture_and_flush_main_window(app);
+    } else {
+        client_state::flush_and_release_without_window_capture(app);
+    }
+    if let Some(state) = app.try_state::<AppState>() {
+        state.desktop_events.stop();
+        retry_bounded(SHUTDOWN_STOP_ATTEMPTS, || {
+            state.manager.stop().map_err(|err| err.to_string())
+        })?;
+    }
+    if capture_window {
+        client_state::release(app);
+    }
+    Ok(())
+}
+
+pub(crate) fn request(app: AppHandle) {
+    apply_event(app, ShutdownEvent::BeginShutdown);
+}
+
+#[cfg(windows)]
+pub(crate) fn request_windows_session_end(app: AppHandle) {
+    if !app
+        .state::<ShutdownCoordinator>()
+        .begin_windows_session_end()
+    {
+        return;
+    }
+
+    let (finished_tx, finished_rx) = std::sync::mpsc::sync_channel(1);
+    let cleanup_app = app.clone();
+    std::thread::spawn(move || {
+        // WM_ENDSESSION runs on the window thread. Do not request renderer flushes or
+        // native window state here: either can marshal back to the blocked thread. The
+        // bounded fallback therefore persists only state already captured in memory.
+        let result = cleanup(&cleanup_app, false);
+        if let Err(err) = &result {
+            eprintln!("[tauri] Windows session-end cleanup failed: {err}");
+        }
+        cleanup_app
+            .state::<ShutdownCoordinator>()
+            .complete_windows_session_end();
+        let _ = finished_tx.send(result);
+    });
+    match finished_rx.recv_timeout(WINDOWS_SESSION_END_TIMEOUT) {
+        Ok(Ok(())) => {}
+        Ok(Err(_)) => {}
+        Err(_) => eprintln!(
+            "[tauri] Windows session-end cleanup exceeded {:?}; returning control to Windows",
+            WINDOWS_SESSION_END_TIMEOUT
+        ),
+    }
+}
+
+pub(crate) fn request_main_window_close(app: AppHandle) {
+    apply_event(app, ShutdownEvent::BeginMainWindowClose);
+}
+
+pub(crate) fn renderer_flushed(app: AppHandle, generation: u64) {
+    apply_event(app, ShutdownEvent::RendererFlushed(generation));
+}
+
+pub(crate) fn main_window_destroyed(app: AppHandle) {
+    apply_event(app, ShutdownEvent::MainWindowDestroyed);
+}
+
+fn phase(app: &AppHandle) -> ShutdownPhase {
+    app.state::<ShutdownCoordinator>().phase()
+}
+
+pub(crate) fn with_navigation_authority<T>(
+    app: &AppHandle,
+    operation: impl FnOnce() -> T,
+) -> Option<T> {
+    app.state::<ShutdownCoordinator>()
+        .with_navigation(operation)
+}
+
+pub(crate) fn main_window_close_allowed(app: &AppHandle) -> bool {
+    phase(app) == ShutdownPhase::MainWindowCloseAllowed
+}
+
+pub(crate) fn exit_allowed(app: &AppHandle) -> bool {
+    phase(app) == ShutdownPhase::ExitAllowed
+}
+
+#[cfg(windows)]
+fn is_confirmed_windows_session_end(message: u32, wparam: usize) -> bool {
+    use windows_sys::Win32::UI::WindowsAndMessaging::WM_ENDSESSION;
+
+    message == WM_ENDSESSION && wparam != 0
+}
+
+#[cfg(windows)]
+struct WindowsSessionEndContext {
+    app: AppHandle,
+}
+
+#[cfg(windows)]
+unsafe extern "system" fn windows_session_end_proc(
+    hwnd: windows_sys::Win32::Foundation::HWND,
+    message: u32,
+    wparam: windows_sys::Win32::Foundation::WPARAM,
+    lparam: windows_sys::Win32::Foundation::LPARAM,
+    subclass_id: usize,
+    reference_data: usize,
+) -> windows_sys::Win32::Foundation::LRESULT {
+    use windows_sys::Win32::UI::Shell::{DefSubclassProc, RemoveWindowSubclass};
+    use windows_sys::Win32::UI::WindowsAndMessaging::{WM_NCDESTROY, WM_QUERYENDSESSION};
+
+    if message == WM_NCDESTROY {
+        RemoveWindowSubclass(hwnd, Some(windows_session_end_proc), subclass_id);
+        let result = DefSubclassProc(hwnd, message, wparam, lparam);
+        drop(Box::from_raw(
+            reference_data as *mut WindowsSessionEndContext,
+        ));
+        return result;
+    }
+
+    if message == WM_QUERYENDSESSION {
+        return 1;
+    }
+
+    if is_confirmed_windows_session_end(message, wparam) {
+        let context = &*(reference_data as *const WindowsSessionEndContext);
+        request_windows_session_end(context.app.clone());
+        return 0;
+    }
+
+    DefSubclassProc(hwnd, message, wparam, lparam)
+}
+
+#[cfg(windows)]
+pub(crate) fn install_windows_session_end_handler(window: &WebviewWindow) -> Result<(), String> {
+    use windows_sys::Win32::UI::Shell::SetWindowSubclass;
+
+    const SUBCLASS_ID: usize = 0x434E_5345;
+    let hwnd = window.hwnd().map_err(|err| err.to_string())?;
+    let context = Box::into_raw(Box::new(WindowsSessionEndContext {
+        app: window.app_handle().clone(),
+    }));
+    let installed = unsafe {
+        SetWindowSubclass(
+            hwnd.0,
+            Some(windows_session_end_proc),
+            SUBCLASS_ID,
+            context as usize,
+        )
+    };
+    if installed == 0 {
+        unsafe { drop(Box::from_raw(context)) };
+        return Err("failed to install Windows session-end handler".to_string());
+    }
+    Ok(())
+}
+
+#[cfg(windows)]
+pub(crate) fn schedule_windows_session_end_handler(window: &WebviewWindow) -> Result<(), String> {
+    let window = window.clone();
+    let app = window.app_handle().clone();
+    app.run_on_main_thread(move || {
+        if let Err(err) = install_windows_session_end_handler(&window) {
+            eprintln!("[client-state] failed to install Windows session-end handler: {err}");
+        }
+    })
+    .map_err(|err| err.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::{mpsc, Arc};
+
+    #[test]
+    fn close_only_flushes_and_closes_without_cleanup() {
+        let waiting = transition(ShutdownPhase::Idle, ShutdownEvent::BeginMainWindowClose);
+        assert_eq!(
+            waiting,
+            (
+                ShutdownPhase::WaitingForMainWindowRenderer,
+                ShutdownAction::RequestRendererFlush
+            )
+        );
+        let flushing = transition(waiting.0, ShutdownEvent::RendererFlushed(1));
+        assert_eq!(
+            flushing,
+            (
+                ShutdownPhase::FlushingMainWindow,
+                ShutdownAction::FlushMainWindow
+            )
+        );
+        assert_eq!(
+            transition(flushing.0, ShutdownEvent::MainWindowFlushed),
+            (
+                ShutdownPhase::MainWindowCloseAllowed,
+                ShutdownAction::CloseMainWindow
+            )
+        );
+    }
+
+    #[test]
+    fn shutdown_promotes_each_close_only_phase() {
+        for (phase, event, expected) in [
+            (
+                ShutdownPhase::WaitingForMainWindowRenderer,
+                ShutdownEvent::BeginShutdown,
+                (
+                    ShutdownPhase::WaitingForShutdownRenderer,
+                    ShutdownAction::None,
+                ),
+            ),
+            (
+                ShutdownPhase::FlushingMainWindow,
+                ShutdownEvent::BeginShutdown,
+                (
+                    ShutdownPhase::FlushingMainWindowForShutdown,
+                    ShutdownAction::None,
+                ),
+            ),
+            (
+                ShutdownPhase::FlushingMainWindowForShutdown,
+                ShutdownEvent::MainWindowFlushed,
+                (
+                    ShutdownPhase::CleanupInProgress,
+                    ShutdownAction::StartCleanup,
+                ),
+            ),
+            (
+                ShutdownPhase::MainWindowCloseAllowed,
+                ShutdownEvent::BeginShutdown,
+                (
+                    ShutdownPhase::CleanupInProgress,
+                    ShutdownAction::StartCleanup,
+                ),
+            ),
+        ] {
+            assert_eq!(transition(phase, event), expected);
+        }
+    }
+
+    #[test]
+    fn stale_renderer_completion_cannot_advance_a_later_close() {
+        let coordinator = ShutdownCoordinator::default();
+        let (_, first) = coordinator.apply(ShutdownEvent::BeginMainWindowClose);
+        assert_eq!(first, Some(1));
+        coordinator.apply(ShutdownEvent::RendererFlushed(1));
+        coordinator.apply(ShutdownEvent::MainWindowFlushed);
+        coordinator.apply(ShutdownEvent::MainWindowDestroyed);
+        let (_, second) = coordinator.apply(ShutdownEvent::BeginMainWindowClose);
+        assert_eq!(second, Some(2));
+        for stale in [
+            ShutdownEvent::RendererFlushed(1),
+            ShutdownEvent::RendererTimeout(1),
+        ] {
+            assert_eq!(coordinator.apply(stale), (ShutdownAction::None, None));
+            assert_eq!(
+                coordinator.phase(),
+                ShutdownPhase::WaitingForMainWindowRenderer
+            );
+        }
+        assert_eq!(
+            coordinator.apply(ShutdownEvent::RendererTimeout(2)).0,
+            ShutdownAction::FlushMainWindow
+        );
+    }
+
+    #[test]
+    fn cleanup_completion_permanently_allows_exit() {
+        let completed = transition(
+            ShutdownPhase::CleanupInProgress,
+            ShutdownEvent::CleanupFinished,
+        );
+        assert_eq!(
+            completed,
+            (ShutdownPhase::ExitAllowed, ShutdownAction::None)
+        );
+        assert_eq!(
+            transition(completed.0, ShutdownEvent::BeginShutdown),
+            (ShutdownPhase::ExitAllowed, ShutdownAction::None)
+        );
+    }
+
+    #[test]
+    fn failed_cleanup_stays_alive_and_accepts_a_later_retry() {
+        assert_eq!(
+            transition(
+                ShutdownPhase::CleanupInProgress,
+                ShutdownEvent::CleanupFailed
+            ),
+            (ShutdownPhase::CleanupBlocked, ShutdownAction::None)
+        );
+        assert_eq!(
+            transition(ShutdownPhase::CleanupBlocked, ShutdownEvent::BeginShutdown),
+            (
+                ShutdownPhase::CleanupInProgress,
+                ShutdownAction::StartCleanup
+            )
+        );
+    }
+
+    #[test]
+    fn shutdown_stop_retries_are_bounded() {
+        let mut attempts = 0;
+        retry_bounded(SHUTDOWN_STOP_ATTEMPTS, || {
+            attempts += 1;
+            (attempts == SHUTDOWN_STOP_ATTEMPTS).then_some(()).ok_or(())
+        })
+        .unwrap();
+        assert_eq!(attempts, SHUTDOWN_STOP_ATTEMPTS);
+
+        let mut failures = 0;
+        assert!(retry_bounded(SHUTDOWN_STOP_ATTEMPTS, || {
+            failures += 1;
+            Err::<(), _>("unconfirmed")
+        })
+        .is_err());
+        assert_eq!(failures, SHUTDOWN_STOP_ATTEMPTS);
+    }
+
+    #[test]
+    fn shutdown_waits_for_the_final_navigation_invocation() {
+        let coordinator = Arc::new(ShutdownCoordinator::default());
+        let navigating = Arc::clone(&coordinator);
+        let (started_tx, started_rx) = mpsc::channel();
+        let (release_tx, release_rx) = mpsc::channel();
+        let navigation = std::thread::spawn(move || {
+            navigating.with_navigation(|| {
+                started_tx.send(()).unwrap();
+                release_rx.recv().unwrap();
+            })
+        });
+        started_rx.recv().unwrap();
+        let shutting_down = Arc::clone(&coordinator);
+        let (finished_tx, finished_rx) = mpsc::channel();
+        let shutdown = std::thread::spawn(move || {
+            shutting_down.apply(ShutdownEvent::BeginShutdown);
+            finished_tx.send(()).unwrap();
+        });
+        assert!(finished_rx.recv_timeout(Duration::from_millis(20)).is_err());
+        release_tx.send(()).unwrap();
+        navigation.join().unwrap();
+        finished_rx.recv_timeout(Duration::from_secs(1)).unwrap();
+        shutdown.join().unwrap();
+        assert_eq!(
+            coordinator.phase(),
+            ShutdownPhase::WaitingForShutdownRenderer
+        );
+        assert!(coordinator.with_navigation(|| ()).is_none());
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_session_end_is_bounded_and_starts_once() {
+        let coordinator = ShutdownCoordinator::default();
+        assert!(coordinator.begin_windows_session_end());
+        assert!(!coordinator.begin_windows_session_end());
+        assert!(WINDOWS_SESSION_END_TIMEOUT <= Duration::from_secs(5));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn only_confirmed_end_session_starts_shutdown() {
+        use windows_sys::Win32::UI::WindowsAndMessaging::{
+            WM_CLOSE, WM_ENDSESSION, WM_QUERYENDSESSION,
+        };
+
+        assert!(!is_confirmed_windows_session_end(WM_QUERYENDSESSION, 0));
+        assert!(is_confirmed_windows_session_end(WM_ENDSESSION, 1));
+        assert!(!is_confirmed_windows_session_end(WM_ENDSESSION, 0));
+        assert!(!is_confirmed_windows_session_end(WM_CLOSE, 0));
+    }
+}
diff --git a/packages/tauri-app/src-tauri/src/windows_update.rs b/packages/tauri-app/src-tauri/src/windows_update.rs
new file mode 100644
index 00000000..7d4ce2cb
--- /dev/null
+++ b/packages/tauri-app/src-tauri/src/windows_update.rs
@@ -0,0 +1,38 @@
+use std::process::Command;
+
+#[cfg(windows)]
+use std::os::windows::process::CommandExt;
+
+#[tauri::command]
+pub async fn install_stable_update() -> Result<(), String> {
+    tauri::async_runtime::spawn_blocking(|| {
+        let mut command = Command::new("winget");
+        command.args([
+            "upgrade",
+            "--exact",
+            "--id",
+            "NeuralNomadsAI.CodeNomad",
+            "--source",
+            "winget",
+            "--silent",
+            "--accept-source-agreements",
+            "--accept-package-agreements",
+            "--disable-interactivity",
+        ]);
+
+        #[cfg(windows)]
+        command.creation_flags(0x08000000);
+
+        let status = command
+            .status()
+            .map_err(|err| format!("Unable to start the WinGet update: {err}"))?;
+
+        if status.success() {
+            Ok(())
+        } else {
+            Err(format!("WinGet update failed with status {status}"))
+        }
+    })
+    .await
+    .map_err(|err| format!("Unable to monitor the WinGet update: {err}"))?
+}
diff --git a/packages/tauri-app/src-tauri/tauri.conf.json b/packages/tauri-app/src-tauri/tauri.conf.json
index 243cc80a..e01de7c3 100644
--- a/packages/tauri-app/src-tauri/tauri.conf.json
+++ b/packages/tauri-app/src-tauri/tauri.conf.json
@@ -26,7 +26,8 @@
         "decorations": true,
         "theme": "Dark",
         "backgroundColor": "#1a1a1a",
-        "zoomHotkeysEnabled": true
+        "zoomHotkeysEnabled": true,
+        "visible": false
       }
     ],
     "security": {
diff --git a/packages/ui/src/App.tsx b/packages/ui/src/App.tsx
index 866a896b..189957c7 100644
--- a/packages/ui/src/App.tsx
+++ b/packages/ui/src/App.tsx
@@ -18,6 +18,9 @@ import { initGithubStars } from "./stores/github-stars"
 
 import { useCommands } from "./lib/hooks/use-commands"
 import { useAppLifecycle } from "./lib/hooks/use-app-lifecycle"
+import { useAppSessionRestore } from "./lib/hooks/use-app-session-restore"
+import { loadedRestorableSession } from "./stores/client-state"
+import { shouldShowAppHomeOverlay, shouldShowEmptyAppHome } from "./stores/app-session-restore-gate"
 import { getLogger } from "./lib/logger"
 import { launchError, showLaunchError, clearLaunchError } from "./stores/launch-errors"
 import { formatLaunchErrorMessage, isMissingBinaryMessage } from "./lib/launch-errors"
@@ -31,10 +34,9 @@ import {
   showFolderSelection,
   setShowFolderSelection,
 } from "./stores/ui"
-import { useConfig } from "./stores/preferences"
+import { recentFolders, useConfig } from "./stores/preferences"
 import {
   createInstance,
-  getExistingInstanceForFolder,
   instances,
   stopInstance,
   disconnectedInstance,
@@ -42,6 +44,7 @@ import {
 } from "./stores/instances"
 import {
   getSessions,
+  getSessionRoot,
   activeSessionId,
   setActiveParentSession,
   clearActiveParentSession,
@@ -65,15 +68,16 @@ import {
   ensureActiveAppTab,
   getAdjacentAppTabId,
   getAppTabById,
+  markAppTabUserInteraction,
   moveAppTab,
   selectAppTab,
   selectInstanceTab,
   selectSidecarTab,
 } from "./stores/app-tabs"
-
 const log = getLogger("actions")
 
 const App: Component = () => {
+  useAppSessionRestore()
   const { t } = useI18n()
   const {
     preferences,
@@ -99,11 +103,6 @@ const App: Component = () => {
   const [escapeInDebounce, setEscapeInDebounce] = createSignal(false)
   const [instanceTabBarHeight, setInstanceTabBarHeight] = createSignal(0)
   const [sidecarPickerOpen, setSidecarPickerOpen] = createSignal(false)
-  const [alreadyOpenFolderChoice, setAlreadyOpenFolderChoice] = createSignal<{
-    folderPath: string
-    binaryPath: string
-    instanceId: string
-  } | null>(null)
   const phoneQuery = useMediaQuery("(max-width: 767px)")
   const isPhoneLayout = createMemo(() => phoneQuery())
 
@@ -280,28 +279,28 @@ const App: Component = () => {
     if (!folderPath) {
       return
     }
+
     const selectedBinary = binaryPath || serverSettings().opencodeBinary || "opencode"
     const projectName = getProjectNameForFolder(folderPath)
-    recordWorkspaceLaunch(folderPath, selectedBinary)
     clearLaunchError()
 
-    if (!options?.forceNew) {
-      const existingInstance = getExistingInstanceForFolder(folderPath)
-      if (existingInstance) {
-        setAlreadyOpenFolderChoice({ folderPath, binaryPath: selectedBinary, instanceId: existingInstance.id })
-        return
-      }
-    }
-
     setIsSelectingFolder(true)
     try {
-      const instanceId = await createInstance(folderPath, selectedBinary, projectName)
-      selectInstanceTab(instanceId)
+      const result = await createInstance(folderPath, selectedBinary, projectName, { forceNew: options?.forceNew })
+      recordWorkspaceLaunch(instances().get(result.instanceId)?.folder ?? folderPath, selectedBinary, folderPath)
+      if (result.reused) {
+        selectInstanceTab(result.instanceId)
+        setShowFolderSelection(false)
+        log.info("Selected reused instance", { instanceId: result.instanceId, folderPath })
+        return
+      }
+
+      selectInstanceTab(result.instanceId)
       setShowFolderSelection(false)
 
       log.info("Created instance", {
-        instanceId,
-        port: instances().get(instanceId)?.port,
+        instanceId: result.instanceId,
+        port: instances().get(result.instanceId)?.port,
       })
     } catch (error) {
       const message = formatLaunchErrorMessage(error, t("app.launchError.fallbackMessage"))
@@ -313,24 +312,13 @@ const App: Component = () => {
     }
   }
 
-  function dismissAlreadyOpenFolderChoice() {
-    setAlreadyOpenFolderChoice(null)
-  }
-
-  function switchToAlreadyOpenFolder() {
-    const choice = alreadyOpenFolderChoice()
-    if (!choice) return
-    setAlreadyOpenFolderChoice(null)
-    selectInstanceTab(choice.instanceId)
+  function handleSelectExistingInstance(instanceId: string, recentPath: string, binaryPath: string) {
+    const instance = instances().get(instanceId)
+    if (!instance) return
+    recordWorkspaceLaunch(instance.folder, binaryPath, recentPath)
+    selectInstanceTab(instanceId)
     setShowFolderSelection(false)
-    log.info("Selected existing instance", { instanceId: choice.instanceId, folderPath: choice.folderPath })
-  }
-
-  function openAnotherFolderInstance() {
-    const choice = alreadyOpenFolderChoice()
-    if (!choice) return
-    setAlreadyOpenFolderChoice(null)
-    void handleSelectFolder(choice.folderPath, choice.binaryPath, { forceNew: true })
+    log.info("Selected existing instance", { instanceId, folderPath: instance.folder })
   }
 
   function handleLaunchErrorClose() {
@@ -408,12 +396,8 @@ const App: Component = () => {
       return
     }
 
-    const parentSessionId = session.parentId ?? session.id
-    const parentSession = sessions.find((s) => s.id === parentSessionId)
-
-    if (!parentSession || parentSession.parentId !== null) {
-      return
-    }
+    const parentSession = getSessionRoot(instanceId, sessionId)
+    if (!parentSession) return
 
     clearActiveParentSession(instanceId)
 
@@ -427,6 +411,7 @@ const App: Component = () => {
   async function handleCloseAppTab(tabId: string) {
     const tab = getAppTabById(tabId)
     if (!tab) return
+    markAppTabUserInteraction()
 
     const fallbackTabId = activeAppTabId() === tabId ? getAdjacentAppTabId(tabId) : activeAppTabId()
 
@@ -500,7 +485,7 @@ const App: Component = () => {
       const tauriBridge = (window as { __TAURI__?: { event?: { listen: (event: string, handler: (event: { payload: unknown }) => void) => Promise<() => void> } } }).__TAURI__
       if (tauriBridge?.event) {
         let unlistenMenu: (() => void) | null = null
-        
+
         tauriBridge.event.listen("menu:newInstance", () => {
           handleNewInstanceRequest()
         }).then((unlisten) => {
@@ -542,7 +527,7 @@ const App: Component = () => {
                    <p class="text-xs font-medium text-muted uppercase tracking-wide mb-1">{t("app.launchError.binaryPathLabel")}</p>
                    <p class="text-sm font-mono text-primary break-all">{launchErrorPath()}</p>
                  </div>
- 
+
                  <Show when={launchErrorMessage()}>
                    <div class="rounded-lg border border-base bg-surface-secondary p-4 flex flex-col gap-2 flex-1 min-h-0">
                      <p class="text-xs font-medium text-muted uppercase tracking-wide">{t("app.launchError.errorOutputLabel")}</p>
@@ -645,18 +630,22 @@ const App: Component = () => {
             </>
           }
         >
-          <FolderSelectionView
-            onSelectFolder={handleSelectFolder}
-            isLoading={isSelectingFolder()}
-            onOpenSidecar={handleOpenSidecarPicker}
-          />
+          <Show when={shouldShowEmptyAppHome(loadedRestorableSession())}>
+            <FolderSelectionView
+              onSelectFolder={handleSelectFolder}
+              onSelectExistingInstance={handleSelectExistingInstance}
+              isLoading={isSelectingFolder()}
+              onOpenSidecar={handleOpenSidecarPicker}
+            />
+          </Show>
         </Show>
 
-        <Show when={showFolderSelection()}>
+        <Show when={shouldShowAppHomeOverlay(showFolderSelection(), appTabs().length)}>
           <div class="fixed inset-0 bg-black/50 z-50 flex items-center justify-center">
             <div class="w-full h-full relative">
               <FolderSelectionView
                 onSelectFolder={handleSelectFolder}
+                onSelectExistingInstance={handleSelectExistingInstance}
                 isLoading={isSelectingFolder()}
                 onOpenSidecar={handleOpenSidecarPicker}
                 onClose={() => {
@@ -667,34 +656,9 @@ const App: Component = () => {
             </div>
           </div>
         </Show>
- 
+
         <SettingsScreen />
         <SideCarPickerDialog open={sidecarPickerOpen()} onClose={() => setSidecarPickerOpen(false)} onOpenSidecar={handleOpenSidecar} />
-        <Show when={alreadyOpenFolderChoice()}>
-          <Dialog open modal onOpenChange={(open) => !open && dismissAlreadyOpenFolderChoice()}>
-            <Dialog.Portal>
-              <Dialog.Overlay class="modal-overlay z-[60]" />
-              <Dialog.Content class="modal-surface fixed left-1/2 top-1/2 z-[1310] w-full max-w-sm -translate-x-1/2 -translate-y-1/2 p-6 border border-base shadow-2xl" tabIndex={-1}>
-                <Dialog.Title class="text-lg font-semibold text-primary">
-                  {t("folderSelection.recent.alreadyOpenTitle")}
-                </Dialog.Title>
-                <Dialog.Description class="text-sm text-secondary mt-1">
-                  {t("folderSelection.recent.alreadyOpenMessage")}
-                </Dialog.Description>
-
-                <div class="mt-6 flex justify-end gap-3">
-                  <button type="button" class="button-secondary" onClick={openAnotherFolderInstance}>
-                    {t("folderSelection.recent.openAnotherInstance")}
-                  </button>
-                  <button type="button" class="button-primary" onClick={switchToAlreadyOpenFolder}>
-                    {t("folderSelection.recent.switchToOpenProject")}
-                  </button>
-                </div>
-              </Dialog.Content>
-            </Dialog.Portal>
-          </Dialog>
-        </Show>
- 
         <AlertDialog />
 
         <Toaster
diff --git a/packages/ui/src/components/focus-conversation.test.ts b/packages/ui/src/components/focus-conversation.test.ts
new file mode 100644
index 00000000..77c20936
--- /dev/null
+++ b/packages/ui/src/components/focus-conversation.test.ts
@@ -0,0 +1,39 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { focusConversationStream } from "./focus-conversation.ts"
+
+describe("focusConversationStream", () => {
+  it("focuses the message stream without scrolling", () => {
+    const calls: Array<FocusOptions | undefined> = []
+    const stream = {
+      focus(options?: FocusOptions) {
+        calls.push(options)
+      },
+    } as unknown as HTMLElement
+    const root = { querySelector: () => stream } as unknown as ParentNode
+
+    assert.equal(focusConversationStream(root), true)
+    assert.deepEqual(calls, [{ preventScroll: true }])
+  })
+
+  it("falls back when focus options are unsupported", () => {
+    const calls: Array<FocusOptions | undefined> = []
+    const stream = {
+      focus(options?: FocusOptions) {
+        calls.push(options)
+        if (options) throw new Error("unsupported")
+      },
+    } as unknown as HTMLElement
+    const root = { querySelector: () => stream } as unknown as ParentNode
+
+    assert.equal(focusConversationStream(root), true)
+    assert.deepEqual(calls, [{ preventScroll: true }, undefined])
+  })
+
+  it("returns false when focus is unavailable", () => {
+    assert.equal(focusConversationStream(null), false)
+    const root = { querySelector: () => null } as unknown as ParentNode
+    assert.equal(focusConversationStream(root), false)
+  })
+})
diff --git a/packages/ui/src/components/focus-conversation.ts b/packages/ui/src/components/focus-conversation.ts
new file mode 100644
index 00000000..074c158a
--- /dev/null
+++ b/packages/ui/src/components/focus-conversation.ts
@@ -0,0 +1,15 @@
+export function focusConversationStream(root: ParentNode | null | undefined): boolean {
+  const stream = root?.querySelector<HTMLElement>(".message-stream")
+  if (!stream) return false
+
+  try {
+    stream.focus({ preventScroll: true })
+  } catch {
+    try {
+      stream.focus()
+    } catch {
+      return false
+    }
+  }
+  return true
+}
diff --git a/packages/ui/src/components/folder-selection-view.tsx b/packages/ui/src/components/folder-selection-view.tsx
index 5a0fc791..af499dcf 100644
--- a/packages/ui/src/components/folder-selection-view.tsx
+++ b/packages/ui/src/components/folder-selection-view.tsx
@@ -1,7 +1,6 @@
 import { Dialog } from "@kobalte/core/dialog"
-import { Select } from "@kobalte/core/select"
 import { Component, createMemo, createSignal, Show, For, onMount, onCleanup, createEffect } from "solid-js"
-import { Folder, Clock, Trash2, FolderPlus, Settings, ChevronRight, MonitorUp, Star, Languages, ChevronDown, X, Globe, Loader2, GitBranch, Pencil } from "lucide-solid"
+import { Folder, Clock, Trash2, FolderPlus, Settings, ChevronRight, MonitorUp, Star, X, Globe, Loader2, GitBranch, Pencil } from "lucide-solid"
 import { useConfig } from "../stores/preferences"
 import DirectoryBrowserDialog from "./directory-browser-dialog"
 import Kbd from "./kbd"
@@ -12,14 +11,16 @@ import VersionPill from "./version-pill"
 import { DiscordSymbolIcon, GitHubMarkIcon } from "./brand-icons"
 import { githubStars } from "../stores/github-stars"
 import { formatCompactCount } from "../lib/formatters"
-import { useI18n, type Locale } from "../lib/i18n"
+import { useI18n } from "../lib/i18n"
 import { showAlertDialog } from "../stores/alerts"
 import { openSettings, settingsOpen } from "../stores/settings-screen"
 import { openExternalUrl } from "../lib/external-url"
 import { serverApi } from "../lib/api-client"
-import { canOpenRemoteWindows, isTauriHost } from "../lib/runtime-env"
-import { openRemoteServerWindow } from "../lib/native/remote-window"
+import { canOpenRemoteWindows } from "../lib/runtime-env"
 import { getExistingInstanceForFolder, updateProjectNameForFolder } from "../stores/instances"
+import { LocaleSelector } from "./locale-selector"
+import { RemoteServerDialog } from "./remote-server-dialog"
+import { useRemoteServerProfiles } from "../lib/hooks/use-remote-server-profiles"
 
 const codeNomadLogo = new URL("../images/CodeNomad-Icon.png", import.meta.url).href
 const GITHUB_URL = "https://github.com/NeuralNomadsAI/CodeNomad"
@@ -30,6 +31,7 @@ type HomeTab = "local" | "servers"
 
 interface FolderSelectionViewProps {
   onSelectFolder: (folder: string, binaryPath?: string, options?: { forceNew?: boolean }) => void
+  onSelectExistingInstance: (instanceId: string, recentPath: string, binaryPath: string) => void
   onOpenSidecar?: () => void
   isLoading?: boolean
   onClose?: () => void
@@ -40,16 +42,13 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
     recentFolders,
     removeRecentFolder,
     renameRecentFolderProject,
-    preferences,
-    updatePreferences,
     serverSettings,
-    remoteServers,
-    saveRemoteServerProfile,
-    markRemoteServerConnected,
-    removeRemoteServerProfile,
   } = useConfig()
-  const { t, locale } = useI18n()
+  const { remoteServers, connectingServerId, saveServer, connectSavedServer, removeRemoteServerProfile } = useRemoteServerProfiles()
+  const { t } = useI18n()
   const [selectedIndex, setSelectedIndex] = createSignal(0)
+  const [hoveredRecentActionPath, setHoveredRecentActionPath] = createSignal<string | null>(null)
+  const [focusedRecentActionPath, setFocusedRecentActionPath] = createSignal<string | null>(null)
   const [focusMode, setFocusMode] = createSignal<"recent" | "new" | null>("recent")
   const [selectedBinary, setSelectedBinary] = createSignal(serverSettings().opencodeBinary || "opencode")
   const [isFolderBrowserOpen, setIsFolderBrowserOpen] = createSignal(false)
@@ -64,32 +63,10 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
   const [isCloningRepository, setIsCloningRepository] = createSignal(false)
   const [activeTab, setActiveTab] = createSignal<HomeTab>("local")
   const [isServerDialogOpen, setIsServerDialogOpen] = createSignal(false)
-  const [serverName, setServerName] = createSignal("")
-  const [serverUrl, setServerUrl] = createSignal("")
-  const [skipTlsVerify, setSkipTlsVerify] = createSignal(false)
-  const [serverDialogError, setServerDialogError] = createSignal<string | null>(null)
-  const [isSavingServer, setIsSavingServer] = createSignal(false)
-  const [connectingServerId, setConnectingServerId] = createSignal<string | null>(null)
   let homeRootRef: HTMLDivElement | undefined
   let actionsColumnRef: HTMLDivElement | undefined
   let recentListRef: HTMLDivElement | undefined
 
-  type LanguageOption = { value: Locale; label: string }
-
-  const languageOptions: LanguageOption[] = [
-    { value: "en", label: "English" },
-    { value: "es", label: "Español" },
-    { value: "fr", label: "Français" },
-    { value: "ru", label: "Русский" },
-    { value: "ja", label: "日本語" },
-    { value: "zh-Hans", label: "简体中文" },
-    { value: "he", label: "עברית" },
-    { value: "de", label: "Deutsch" },
-    { value: "ne", label: "नेपाली" },
-  ]
-
-  const selectedLanguageOption = () => languageOptions.find((opt) => opt.value === locale()) ?? languageOptions[0]
-  
   const folders = () => recentFolders()
   const serverList = () => remoteServers()
   const isLoading = () => Boolean(props.isLoading)
@@ -133,6 +110,7 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
     const isEditingField =
       activeElement &&
       (["INPUT", "TEXTAREA", "SELECT"].includes(activeElement.tagName) || activeElement.isContentEditable || Boolean(insideModal))
+    const isInteractiveControl = activeElement && ["BUTTON", "A"].includes(activeElement.tagName)
 
     if (isEditingField) {
       return
@@ -155,6 +133,8 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
       return
     }
 
+    if (isInteractiveControl && (e.key === "Enter" || e.key === " ")) return
+
     const listLength = getActiveListLength()
     if (listLength === 0) return
 
@@ -209,14 +189,14 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
     if (activeTab() === "local") {
       const folder = folders()[index]
       if (folder) {
-        handleFolderSelect(folder.path)
+        handleFolderSelect(folder.path, true)
       }
       return
     }
 
     const server = serverList()[index]
     if (server) {
-      void handleConnectSavedServer(server.id)
+      void connectSavedServer(server.id)
     }
   }
 
@@ -309,9 +289,27 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
     return t("time.relative.justNow")
   }
 
-  function handleFolderSelect(path: string) {
+  function handleFolderSelect(path: string, forceNew = false) {
     if (isLoading()) return
-    props.onSelectFolder(path, selectedBinary())
+    props.onSelectFolder(path, selectedBinary(), forceNew ? { forceNew: true } : undefined)
+  }
+
+  function handleExistingInstanceSelect(instanceId: string, recentPath: string) {
+    if (isLoading()) return
+    props.onSelectExistingInstance(instanceId, recentPath, selectedBinary())
+  }
+
+  function setRecentActionHovered(path: string, active: boolean) {
+    setHoveredRecentActionPath((current) => active ? path : current === path ? null : current)
+  }
+
+  function setRecentActionFocused(path: string, active: boolean) {
+    setFocusedRecentActionPath((current) => active ? path : current === path ? null : current)
+  }
+
+  function clearRecentActionState(path: string) {
+    setRecentActionHovered(path, false)
+    setRecentActionFocused(path, false)
   }
 
   function resetCloneDialog() {
@@ -354,109 +352,11 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
     }
   }
 
-  function resetServerDialog() {
-    setServerName("")
-    setServerUrl("")
-    setSkipTlsVerify(false)
-    setServerDialogError(null)
-  }
-
   function openServerDialog() {
     if (!canUseRemoteServerWindows()) return
-    resetServerDialog()
     setIsServerDialogOpen(true)
   }
 
-  async function probeAndOpenServer(input: { id?: string; name: string; baseUrl: string; skipTlsVerify: boolean }, openWindow: boolean) {
-    if (openWindow && !canUseRemoteServerWindows()) {
-      throw new Error("Remote server windows can only be opened from a local desktop window")
-    }
-
-    const trimmedName = input.name.trim()
-    const trimmedUrl = input.baseUrl.trim()
-    if (!trimmedName || !trimmedUrl) {
-      throw new Error(t("folderSelection.servers.dialog.errorRequired"))
-    }
-
-    const probe = await serverApi.probeRemoteServer({
-      baseUrl: trimmedUrl,
-      skipTlsVerify: input.skipTlsVerify,
-    })
-
-    if (!probe.ok) {
-      throw new Error(probe.error || t("folderSelection.servers.dialog.errorConnect"))
-    }
-
-    const profile = await saveRemoteServerProfile({
-      id: input.id,
-      name: trimmedName,
-      baseUrl: probe.normalizedUrl,
-      skipTlsVerify: input.skipTlsVerify,
-    })
-
-    if (openWindow) {
-      const remoteProxySession =
-        isTauriHost() && profile.skipTlsVerify && profile.baseUrl.startsWith("https://")
-          ? await serverApi.createRemoteProxySession({
-              baseUrl: profile.baseUrl,
-              skipTlsVerify: profile.skipTlsVerify,
-            })
-          : undefined
-
-      try {
-        await openRemoteServerWindow(profile, remoteProxySession?.windowUrl, remoteProxySession?.sessionId)
-      } catch (error) {
-        if (remoteProxySession) {
-          void serverApi.deleteRemoteProxySession(remoteProxySession.sessionId).catch(() => {})
-        }
-        throw error
-      }
-
-      await markRemoteServerConnected(profile.id)
-    }
-
-    return profile
-  }
-
-  async function handleSaveServer(openWindow: boolean) {
-    if (isSavingServer()) return
-    setIsSavingServer(true)
-    setServerDialogError(null)
-    try {
-      await probeAndOpenServer(
-        {
-          name: serverName(),
-          baseUrl: serverUrl(),
-          skipTlsVerify: skipTlsVerify(),
-        },
-        openWindow,
-      )
-      setIsServerDialogOpen(false)
-      resetServerDialog()
-    } catch (error) {
-      setServerDialogError(error instanceof Error ? error.message : String(error))
-    } finally {
-      setIsSavingServer(false)
-    }
-  }
-
-  async function handleConnectSavedServer(id: string) {
-    if (!canUseRemoteServerWindows()) return
-    const target = remoteServers().find((entry) => entry.id === id)
-    if (!target || connectingServerId()) return
-    setConnectingServerId(id)
-    try {
-      await probeAndOpenServer(target, true)
-    } catch (error) {
-      showAlertDialog(error instanceof Error ? error.message : String(error), {
-        title: t("folderSelection.servers.errorTitle"),
-        variant: "warning",
-      })
-    } finally {
-      setConnectingServerId(null)
-    }
-  }
-
   async function handleBrowse() {
     if (isLoading()) return
     setFocusMode("new")
@@ -623,54 +523,13 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
           aria-busy={isLoading() ? "true" : "false"}
         >
           <div class="absolute top-4" style="inset-inline-start: 1.5rem;">
-            <Select<LanguageOption>
-              value={selectedLanguageOption()}
-              onChange={(value) => {
-                if (!value) return
-                if (value.value === locale()) return
-                updatePreferences({ locale: value.value })
-              }}
-              options={languageOptions}
-              optionValue="value"
-              optionTextValue="label"
-              itemComponent={(itemProps) => (
-                <Select.Item item={itemProps.item} class="selector-option">
-                  <Select.ItemLabel class="selector-option-label">{itemProps.item.rawValue.label}</Select.ItemLabel>
-                </Select.Item>
-              )}
-            >
-              <Select.Trigger
-                class="selector-trigger"
-                aria-label={t("folderSelection.language.ariaLabel")}
-                title={t("folderSelection.language.ariaLabel")}
-              >
-                <Languages class="w-4 h-4 icon-muted" aria-hidden="true" />
-                <div class="flex-1 min-w-0">
-                  <Select.Value<LanguageOption>>
-                    {(state) => (
-                      <span class="selector-trigger-primary selector-trigger-primary--align-left">
-                        {state.selectedOption()?.label}
-                      </span>
-                    )}
-                  </Select.Value>
-                </div>
-                <Select.Icon class="selector-trigger-icon">
-                  <ChevronDown class="w-3 h-3" />
-                </Select.Icon>
-              </Select.Trigger>
-
-              <Select.Portal>
-                <Select.Content class="selector-popover min-w-[180px]">
-                  <Select.Listbox class="selector-listbox" />
-                </Select.Content>
-              </Select.Portal>
-            </Select>
+            <LocaleSelector />
           </div>
           <div class="absolute top-4 flex items-center gap-2" style="inset-inline-end: 1.5rem;">
             <button
               type="button"
               class="selector-button selector-button-secondary w-auto p-2 inline-flex items-center justify-center"
-              onClick={() => openSettings("appearance")}
+              onClick={() => openSettings("general")}
               aria-label={t("settings.open.title")}
               title={t("settings.open.title")}
             >
@@ -869,7 +728,7 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
                                   <button
                                     data-list-index={index()}
                                     class="panel-list-item-content flex-1"
-                                    onClick={() => void handleConnectSavedServer(server.id)}
+                                    onClick={() => void connectSavedServer(server.id)}
                                     onMouseEnter={() => {
                                       setFocusMode("recent")
                                       setSelectedIndex(index())
@@ -893,7 +752,8 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
                                   <button
                                     onClick={() => removeRemoteServerProfile(server.id)}
                                     class="p-2 transition-all hover:bg-red-100 dark:hover:bg-red-900/30 opacity-70 hover:opacity-100 rounded"
-                                    title={t("folderSelection.servers.remove")}
+                                    title={`${t("folderSelection.servers.remove")}: ${server.name}`}
+                                    aria-label={`${t("folderSelection.servers.remove")}: ${server.name}`}
                                   >
                                     <Trash2 class="w-3.5 h-3.5 transition-colors icon-muted hover:text-red-600 dark:hover:text-red-400" />
                                   </button>
@@ -924,37 +784,83 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
                         <For each={folders()}>
                           {(folder, index) => {
                             const existingInstance = () => getExistingInstanceForFolder(folder.path)
+                            const projectName = () => getProjectDisplayName(folder.path, folder.projectName)
+                            const projectLabelId = () => `recent-folder-${index()}-name`
+                            const openActionLabelId = () => `recent-folder-${index()}-open-action`
 
                             return <div
-                              class="panel-list-item"
+                              class="panel-list-item folder-home-recent-item"
                               classList={{
                                 "panel-list-item-highlight": focusMode() === "recent" && selectedIndex() === index(),
                                 "panel-list-item-disabled": isLoading(),
+                                "folder-home-recent-item-action-active":
+                                  hoveredRecentActionPath() === folder.path || focusedRecentActionPath() === folder.path,
+                              }}
+                              onMouseEnter={() => {
+                                if (isLoading()) return
+                                setFocusMode("recent")
+                                setSelectedIndex(index())
                               }}
                             >
                               <div class="flex items-center gap-2 w-full px-1">
-                                <button
-                                  data-list-index={index()}
-                                  class="panel-list-item-content flex-1"
-                                  disabled={isLoading()}
-                                  onClick={() => handleFolderSelect(folder.path)}
-                                  onMouseEnter={() => {
-                                    if (isLoading()) return
-                                    setFocusMode("recent")
-                                    setSelectedIndex(index())
-                                  }}
-                                >
-                                  <div class="flex items-center justify-between gap-3 w-full">
+                                <div class="panel-list-item-content relative flex-1">
+                                  <button
+                                    data-list-index={index()}
+                                    type="button"
+                                    class="folder-home-recent-primary-action"
+                                    disabled={isLoading()}
+                                    aria-labelledby={projectLabelId()}
+                                    title={t("folderSelection.recent.openNewInstance")}
+                                    onClick={() => handleFolderSelect(folder.path, true)}
+                                    onFocus={() => {
+                                      setFocusMode("recent")
+                                      setSelectedIndex(index())
+                                    }}
+                                  />
+                                  <div class="relative z-[1] pointer-events-none flex items-center justify-between gap-3 w-full">
                                     <div class="flex-1 min-w-0">
                                       <div class="flex items-center gap-2 mb-1">
                                         <Folder class="w-4 h-4 flex-shrink-0 icon-muted" />
-                                        <span class="text-sm font-medium truncate text-primary">
-                                          {getProjectDisplayName(folder.path, folder.projectName)}
+                                        <span id={projectLabelId()} class="text-sm font-medium truncate text-primary">
+                                          {projectName()}
                                         </span>
                                         <Show when={existingInstance()}>
-                                          <span class="rounded-full border border-base px-2 py-0.5 text-[10px] font-medium uppercase tracking-wide text-secondary">
-                                            {t("folderSelection.recent.openBadge")}
-                                          </span>
+                                          {(instance) => {
+                                            let ownsHoverState = false
+                                            let ownsFocusState = false
+                                            onCleanup(() => {
+                                              if (ownsHoverState) setRecentActionHovered(folder.path, false)
+                                              if (ownsFocusState) setRecentActionFocused(folder.path, false)
+                                            })
+                                            return (
+                                              <button
+                                                type="button"
+                                                class="folder-home-open-instance-button folder-home-row-action pointer-events-auto"
+                                                disabled={isLoading()}
+                                                aria-labelledby={`${openActionLabelId()} ${projectLabelId()}`}
+                                                title={t("folderSelection.recent.switchToOpenProject")}
+                                                onClick={() => handleExistingInstanceSelect(instance().id, folder.path)}
+                                                onMouseEnter={() => {
+                                                  ownsHoverState = true
+                                                  setRecentActionHovered(folder.path, true)
+                                                }}
+                                                onMouseLeave={() => {
+                                                  ownsHoverState = false
+                                                  setRecentActionHovered(folder.path, false)
+                                                }}
+                                                onFocus={() => {
+                                                  ownsFocusState = true
+                                                  setRecentActionFocused(folder.path, true)
+                                                }}
+                                                onBlur={() => {
+                                                  ownsFocusState = false
+                                                  setRecentActionFocused(folder.path, false)
+                                                }}
+                                              >
+                                                <span id={openActionLabelId()}>{t("folderSelection.recent.openBadge")}</span>
+                                              </button>
+                                            )
+                                          }}
                                         </Show>
                                       </div>
                                       <div class="flex items-center gap-2 pl-6 text-xs text-muted min-w-0">
@@ -968,20 +874,31 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
                                       <kbd class="kbd">↵</kbd>
                                     </Show>
                                   </div>
-                                </button>
+                                </div>
                                 <button
                                   onClick={(e) => openProjectRename(folder.path, folder.projectName, e)}
                                   disabled={isLoading()}
-                                  class="p-2 transition-all hover:bg-surface-hover opacity-70 hover:opacity-100 rounded"
+                                  class="folder-home-row-action p-2 transition-all hover:bg-surface-hover opacity-70 hover:opacity-100 rounded"
                                   title={t("folderSelection.recent.rename")}
+                                  onMouseEnter={() => setRecentActionHovered(folder.path, true)}
+                                  onMouseLeave={() => setRecentActionHovered(folder.path, false)}
+                                  onFocus={() => setRecentActionFocused(folder.path, true)}
+                                  onBlur={() => setRecentActionFocused(folder.path, false)}
                                 >
                                   <Pencil class="w-3.5 h-3.5 transition-colors icon-muted" />
                                 </button>
                                 <button
-                                  onClick={(e) => handleRemove(folder.path, e)}
+                                  onClick={(e) => {
+                                    clearRecentActionState(folder.path)
+                                    handleRemove(folder.path, e)
+                                  }}
                                   disabled={isLoading()}
-                                  class="p-2 transition-all hover:bg-red-100 dark:hover:bg-red-900/30 opacity-70 hover:opacity-100 rounded"
+                                  class="folder-home-row-action p-2 transition-all hover:bg-red-100 dark:hover:bg-red-900/30 opacity-70 hover:opacity-100 rounded"
                                   title={t("folderSelection.recent.remove")}
+                                  onMouseEnter={() => setRecentActionHovered(folder.path, true)}
+                                  onMouseLeave={() => setRecentActionHovered(folder.path, false)}
+                                  onFocus={() => setRecentActionFocused(folder.path, true)}
+                                  onBlur={() => setRecentActionFocused(folder.path, false)}
                                 >
                                   <Trash2 class="w-3.5 h-3.5 transition-colors icon-muted hover:text-red-600 dark:hover:text-red-400" />
                                 </button>
@@ -1245,81 +1162,7 @@ const FolderSelectionView: Component<FolderSelectionViewProps> = (props) => {
         </Dialog.Portal>
       </Dialog>
 
-      <Dialog open={isServerDialogOpen()} onOpenChange={(open) => !open && setIsServerDialogOpen(false)}>
-        <Dialog.Portal>
-          <Dialog.Overlay class="modal-overlay" />
-          <div class="fixed inset-0 z-[1300] flex items-center justify-center p-4">
-            <Dialog.Content class="modal-surface w-full max-w-lg p-6 flex flex-col gap-5" tabIndex={-1}>
-              <div>
-                <Dialog.Title class="text-xl font-semibold text-primary">
-                  {t("folderSelection.servers.dialog.title")}
-                </Dialog.Title>
-                <Dialog.Description class="text-sm text-secondary mt-2">
-                  {t("folderSelection.servers.dialog.description")}
-                </Dialog.Description>
-              </div>
-
-              <label class="flex flex-col gap-2 text-sm text-secondary">
-                <span>{t("folderSelection.servers.dialog.name")}</span>
-                <input
-                  class="selector-input w-full"
-                  value={serverName()}
-                  onInput={(event) => setServerName(event.currentTarget.value)}
-                  placeholder={t("folderSelection.servers.dialog.namePlaceholder")}
-                />
-              </label>
-
-              <label class="flex flex-col gap-2 text-sm text-secondary">
-                <span>{t("folderSelection.servers.dialog.url")}</span>
-                <input
-                  class="selector-input w-full"
-                  value={serverUrl()}
-                  onInput={(event) => setServerUrl(event.currentTarget.value)}
-                  placeholder={t("folderSelection.servers.dialog.urlPlaceholder")}
-                />
-              </label>
-
-              <label class="flex items-start gap-3 text-sm text-secondary">
-                <input
-                  type="checkbox"
-                  checked={skipTlsVerify()}
-                  onChange={(event) => setSkipTlsVerify(event.currentTarget.checked)}
-                />
-                <span>{t("folderSelection.servers.dialog.skipTls")}</span>
-              </label>
-
-              <Show when={serverDialogError()}>
-                {(message) => <p class="text-sm text-red-500 break-words">{message()}</p>}
-              </Show>
-
-              <div class="flex items-center justify-end gap-3">
-                <button class="selector-button selector-button-secondary w-auto px-4" onClick={() => setIsServerDialogOpen(false)}>
-                  {t("folderSelection.servers.dialog.cancel")}
-                </button>
-                <button
-                  class="selector-button selector-button-secondary w-auto px-4"
-                  disabled={isSavingServer()}
-                  onClick={() => void handleSaveServer(false)}
-                >
-                  {t("folderSelection.servers.dialog.save")}
-                </button>
-                <button
-                  class="selector-button selector-button-secondary w-auto px-4"
-                  disabled={isSavingServer()}
-                  onClick={() => void handleSaveServer(true)}
-                >
-                  <Show when={isSavingServer()} fallback={<span>{t("folderSelection.servers.dialog.connect")}</span>}>
-                    <span class="inline-flex items-center gap-2">
-                      <Loader2 class="w-4 h-4 animate-spin" />
-                      {t("folderSelection.servers.dialog.connecting")}
-                    </span>
-                  </Show>
-                </button>
-              </div>
-            </Dialog.Content>
-          </div>
-        </Dialog.Portal>
-      </Dialog>
+      <RemoteServerDialog open={isServerDialogOpen()} onOpenChange={setIsServerDialogOpen} onSubmit={saveServer} />
     </>
   )
 }
diff --git a/packages/ui/src/components/instance-tabs.tsx b/packages/ui/src/components/instance-tabs.tsx
index 54866708..6de898c0 100644
--- a/packages/ui/src/components/instance-tabs.tsx
+++ b/packages/ui/src/components/instance-tabs.tsx
@@ -226,7 +226,7 @@ const InstanceTabs: Component<InstanceTabsProps> = (props) => {
 
               <button
                 class="new-tab-button"
-                onClick={() => openSettings("appearance")}
+                onClick={() => openSettings("general")}
                 title={t("settings.open.title")}
                 aria-label={t("settings.open.ariaLabel")}
               >
diff --git a/packages/ui/src/components/instance/instance-shell2.tsx b/packages/ui/src/components/instance/instance-shell2.tsx
index cf3e8ab4..004d85d1 100644
--- a/packages/ui/src/components/instance/instance-shell2.tsx
+++ b/packages/ui/src/components/instance/instance-shell2.tsx
@@ -69,6 +69,7 @@ import { useDrawerResize } from "./shell/useDrawerResize"
 import { useSessionCache } from "./shell/useSessionCache"
 import { useInstanceSessionContext } from "./shell/useInstanceSessionContext"
 import { isPermissionAutoAcceptEnabled } from "../../stores/permission-auto-accept"
+import { readClientLayoutValue, writeClientLayoutValue } from "../../stores/client-state"
 
 const log = getLogger("session")
 const OPEN_SESSION_SEARCH_EVENT = "codenomad:open-session-search"
@@ -127,6 +128,7 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
   const [draftModel, setDraftModel] = createSignal({ providerId: "", modelId: "" })
   const [draftModelManuallySelected, setDraftModelManuallySelected] = createSignal(false)
   const [draftPromptInputApi, setDraftPromptInputApi] = createSignal<PromptInputApi | null>(null)
+  const [focusConversationSessionId, setFocusConversationSessionId] = createSignal<string | null>(null)
 
   // Worktree selector manages its own dialogs.
   const [showSessionSearch, setShowSessionSearch] = createSignal(false)
@@ -171,6 +173,7 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
 
   const drawerChrome = useDrawerChrome({
     t,
+    active: () => Boolean(props.isActiveInstance),
     layoutMode,
     leftPinningSupported,
     rightPinningSupported,
@@ -254,7 +257,7 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
   onMount(() => {
     if (typeof window === "undefined") return
 
-    const savedLeft = window.localStorage.getItem(LEFT_DRAWER_STORAGE_KEY)
+    const savedLeft = readClientLayoutValue(LEFT_DRAWER_STORAGE_KEY)
     if (savedLeft) {
       const parsed = Number.parseInt(savedLeft, 10)
       if (Number.isFinite(parsed)) {
@@ -263,7 +266,7 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
     }
 
     let didLoadRightWidth = false
-    const savedRight = window.localStorage.getItem(RIGHT_DRAWER_STORAGE_KEY)
+    const savedRight = readClientLayoutValue(RIGHT_DRAWER_STORAGE_KEY)
     if (savedRight) {
       const parsed = Number.parseInt(savedRight, 10)
       if (Number.isFinite(parsed)) {
@@ -291,14 +294,12 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
     onCleanup(() => window.removeEventListener("resize", handleResize))
   })
 
-   createEffect(() => {
-     if (typeof window === "undefined") return
-     window.localStorage.setItem(LEFT_DRAWER_STORAGE_KEY, sessionSidebarWidth().toString())
-   })
+  createEffect(() => {
+    writeClientLayoutValue(LEFT_DRAWER_STORAGE_KEY, sessionSidebarWidth().toString())
+  })
 
   createEffect(() => {
-    if (typeof window === "undefined") return
-    window.localStorage.setItem(RIGHT_DRAWER_STORAGE_KEY, rightDrawerWidth().toString())
+    writeClientLayoutValue(RIGHT_DRAWER_STORAGE_KEY, rightDrawerWidth().toString())
   })
 
   createEffect(() => {
@@ -506,13 +507,13 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
 
   const renderSessionHeaderIndicators = () => (
     <div class="flex items-center flex-wrap justify-center gap-2">
-      {renderYoloModePill()}
       <Show when={hasPendingRequests()} fallback={renderActiveSessionStatusPill()}>
         <PermissionNotificationBanner
           instanceId={props.instance.id}
           onClick={() => setPermissionModalOpen(true)}
         />
       </Show>
+      {renderYoloModePill()}
     </div>
   )
 
@@ -952,6 +953,22 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
     }
   }
 
+  function getActiveCreatedSessionPane(sessionId: string) {
+    if (activeSessionIdForInstance() !== sessionId) return null
+    const pane = sessionCenterEl()?.querySelector<HTMLElement>('.session-cache-pane[data-session-active="true"]')
+    return pane?.dataset.sessionId === sessionId ? pane : null
+  }
+
+  function focusCreatedSessionPrompt(sessionId: string) {
+    const textarea = getActiveCreatedSessionPane(sessionId)?.querySelector<HTMLTextAreaElement>(".prompt-input")
+    if (!textarea || textarea.disabled) return
+    try {
+      textarea.focus({ preventScroll: true })
+    } catch {
+      textarea.focus()
+    }
+  }
+
   async function createAndActivateDraftSession() {
     const agent = draftAgent()
     const model = draftModel()
@@ -962,23 +979,33 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
     if (model.providerId && model.modelId) {
       await updateSessionModel(props.instance.id, session.id, model)
     }
+    if (!window.matchMedia?.("(pointer: coarse)")?.matches || window.matchMedia?.("(any-pointer: fine)")?.matches) {
+      setFocusConversationSessionId(session.id)
+    }
     setActiveParentSession(props.instance.id, session.id)
     return session
   }
 
-  async function handleFirstPromptSend(prompt: string, attachments: Attachment[]) {
+  async function runFirstPromptSubmission(submit: (sessionId: string) => Promise<void>) {
     const session = await createAndActivateDraftSession()
-    await sendMessage(props.instance.id, session.id, prompt, attachments)
+    try {
+      await submit(session.id)
+    } catch (error) {
+      focusCreatedSessionPrompt(session.id)
+      throw error
+    }
+  }
+
+  async function handleFirstPromptSend(prompt: string, attachments: Attachment[]) {
+    await runFirstPromptSubmission((sessionId) => sendMessage(props.instance.id, sessionId, prompt, attachments))
   }
 
   async function handleFirstPromptCommand(commandName: string, args: string) {
-    const session = await createAndActivateDraftSession()
-    await executeCustomCommand(props.instance.id, session.id, commandName, args)
+    await runFirstPromptSubmission((sessionId) => executeCustomCommand(props.instance.id, sessionId, commandName, args))
   }
 
   async function handleFirstPromptShell(command: string) {
-    const session = await createAndActivateDraftSession()
-    await runShellCommand(props.instance.id, session.id, command)
+    await runFirstPromptSubmission((sessionId) => runShellCommand(props.instance.id, sessionId, command))
   }
 
   /** Return to the last conversation */
@@ -1287,6 +1314,10 @@ const InstanceShell2: Component<InstanceShellProps> = (props) => {
                           escapeInDebounce={props.escapeInDebounce}
                           isPhoneLayout={isPhoneLayout()}
                           compactPromptLayout={compactPromptLayout()}
+                          focusConversationOnActivate={focusConversationSessionId() === sessionId}
+                          onConversationFocusHandled={() => {
+                            if (focusConversationSessionId() === sessionId) setFocusConversationSessionId(null)
+                          }}
                           registerSessionPromptApi={registerSessionPromptApi}
                           showSidebarToggle={showEmbeddedSidebarToggle()}
                           onSidebarToggle={() => setLeftOpen(true)}
diff --git a/packages/ui/src/components/instance/shell/SessionSidebar.tsx b/packages/ui/src/components/instance/shell/SessionSidebar.tsx
index 38628e80..fa80c1db 100644
--- a/packages/ui/src/components/instance/shell/SessionSidebar.tsx
+++ b/packages/ui/src/components/instance/shell/SessionSidebar.tsx
@@ -18,6 +18,7 @@ import AgentSelector from "../../agent-selector"
 import ModelSelector from "../../model-selector"
 import ThinkingSelector from "../../thinking-selector"
 import { getLogger } from "../../../lib/logger"
+import { shouldMountSessionList } from "../../session-list-visibility"
 
 const log = getLogger("session")
 
@@ -130,21 +131,23 @@ const SessionSidebar: Component<SessionSidebarProps> = (props) => (
       </div>
 
       <div class="session-sidebar flex flex-col flex-1 min-h-0">
-        <SessionList
-          instanceId={props.instanceId}
-          threads={props.threads()}
-          activeSessionId={props.activeSessionId()}
-          onSelect={props.onSelectSession}
-          onNew={() => {
-            const result = props.onNewSession()
-            if (result instanceof Promise) {
-              void result.catch((error) => log.error("Failed to create session:", error))
-            }
-          }}
-          enableFilterBar={props.showSearch()}
-          showHeader={false}
-          showFooter={false}
-        />
+        <Show when={shouldMountSessionList(props.drawerState())}>
+          <SessionList
+            instanceId={props.instanceId}
+            threads={props.threads()}
+            activeSessionId={props.activeSessionId()}
+            onSelect={props.onSelectSession}
+            onNew={() => {
+              const result = props.onNewSession()
+              if (result instanceof Promise) {
+                void result.catch((error) => log.error("Failed to create session:", error))
+              }
+            }}
+            enableFilterBar={props.showSearch()}
+            showHeader={false}
+            showFooter={false}
+          />
+        </Show>
 
         <div class="session-sidebar-separator" />
         <Show
diff --git a/packages/ui/src/components/instance/shell/right-panel/RightPanel.tsx b/packages/ui/src/components/instance/shell/right-panel/RightPanel.tsx
index 231c1834..64f19547 100644
--- a/packages/ui/src/components/instance/shell/right-panel/RightPanel.tsx
+++ b/packages/ui/src/components/instance/shell/right-panel/RightPanel.tsx
@@ -1,4 +1,5 @@
 import {
+  For,
   Show,
   Suspense,
   createEffect,
@@ -11,10 +12,19 @@ import {
 } from "solid-js"
 import type { ToolState } from "@opencode-ai/sdk/v2"
 import type { FileContent, FileNode } from "@opencode-ai/sdk/v2/client"
+import {
+  DragDropProvider,
+  DragDropSensors,
+  SortableProvider,
+  closestCenter,
+  createSortable,
+  type DragEvent as SolidDndDragEvent,
+} from "@thisbeyond/solid-dnd"
 import IconButton from "@suid/material/IconButton"
 import MenuOpenIcon from "@suid/icons-material/MenuOpen"
 import PushPinIcon from "@suid/icons-material/PushPin"
 import PushPinOutlinedIcon from "@suid/icons-material/PushPinOutlined"
+import { Settings2 } from "lucide-solid"
 
 import type { Instance } from "../../../../types/instance"
 import type { BackgroundProcess } from "../../../../../../server/src/api-types"
@@ -35,6 +45,7 @@ import { requestData } from "../../../../lib/opencode-api"
 import { serverApi } from "../../../../lib/api-client"
 import { showConfirmDialog } from "../../../../stores/alerts"
 import { showToastNotification } from "../../../../lib/notifications"
+import { readClientLayoutValue, writeClientLayoutValue } from "../../../../stores/client-state"
 import { useGlobalPointerDrag } from "../useGlobalPointerDrag"
 import { useGitChanges } from "./useGitChanges"
 import {
@@ -52,12 +63,24 @@ import {
   RIGHT_PANEL_GIT_CHANGES_SPLIT_WIDTH_KEY,
   RIGHT_PANEL_GIT_CHANGES_UNSTAGED_OPEN_NONPHONE_KEY,
   RIGHT_PANEL_GIT_CHANGES_UNSTAGED_OPEN_PHONE_KEY,
+  RIGHT_PANEL_CUSTOMIZATION_STORAGE_KEY,
   RIGHT_PANEL_TAB_STORAGE_KEY,
   readStoredBool,
   readStoredEnum,
   readStoredPanelWidth,
   readStoredRightPanelTab,
 } from "../storage"
+import {
+  applyRightPanelItemCustomization,
+  collectRightPanelItems,
+  parseRightPanelCustomization,
+  setRightPanelItemHidden,
+  type RightPanelCustomization,
+  type RightPanelModule,
+  type RightPanelSectionModule,
+  type RightPanelTabModule,
+} from "./registry"
+import { CORE_STATUS_SECTION_ITEMS } from "./tabs/status-sections"
 
 const LazyGitChangesTab = lazy(() => import("./tabs/GitChangesTab"))
 const LazyFilesTab = lazy(() => import("./tabs/FilesTab"))
@@ -67,6 +90,32 @@ function RightPanelTabFallback() {
   return <div class="flex-1 min-h-0" />
 }
 
+interface SortableRightPanelTabProps {
+  tab: RightPanelTabModule
+  active: boolean
+  label: string
+  dragTitle: string
+  onSelect: () => void
+}
+
+const SortableRightPanelTab: Component<SortableRightPanelTabProps> = (props) => {
+  const sortable = createSortable(props.tab.id)
+  return (
+    <div ref={sortable} class={`right-panel-tab-draggable ${sortable.isActiveDraggable ? "right-panel-tab-draggable-active" : ""}`}>
+      <button
+        type="button"
+        role="tab"
+        class={`right-panel-tab ${props.active ? "right-panel-tab-active" : "right-panel-tab-inactive"}`}
+        aria-selected={props.active}
+        title={props.dragTitle}
+        onClick={props.onSelect}
+      >
+        <span class="tab-label">{props.label}</span>
+      </button>
+    </div>
+  )
+}
+
 interface RightPanelProps {
   t: (key: string, vars?: Record<string, any>) => string
 
@@ -97,8 +146,12 @@ interface RightPanelProps {
 
 const RightPanel: Component<RightPanelProps> = (props) => {
   const [rightPanelTab, setRightPanelTab] = createSignal<RightPanelTab>(readStoredRightPanelTab("git-changes"))
-  const defaultStatusSectionIds = ["yolo-mode", "plan", "background-processes", "mcp", "lsp", "plugins"]
+  const defaultStatusSectionIds = CORE_STATUS_SECTION_ITEMS.map((section) => section.id)
   const [rightPanelExpandedItems, setRightPanelExpandedItems] = createSignal<string[]>(defaultStatusSectionIds)
+  const [rightPanelCustomizationOpen, setRightPanelCustomizationOpen] = createSignal(false)
+  const [rightPanelCustomization, setRightPanelCustomization] = createSignal<RightPanelCustomization>(
+    parseRightPanelCustomization(readClientLayoutValue(RIGHT_PANEL_CUSTOMIZATION_STORAGE_KEY)),
+  )
 
   const [browserPath, setBrowserPath] = createSignal(".")
   const [browserEntries, setBrowserEntries] = createSignal<FileNode[] | null>(null)
@@ -163,13 +216,11 @@ const RightPanel: Component<RightPanelProps> = (props) => {
   }
 
   const persistListOpen = (tab: "git-changes" | "files", value: boolean) => {
-    if (typeof window === "undefined") return
-    window.localStorage.setItem(listOpenStorageKey(tab), value ? "true" : "false")
+    writeClientLayoutValue(listOpenStorageKey(tab), value ? "true" : "false")
   }
 
   const persistGitSectionOpen = (section: "staged" | "unstaged", value: boolean) => {
-    if (typeof window === "undefined") return
-    window.localStorage.setItem(gitSectionStorageKey(section), value ? "true" : "false")
+    writeClientLayoutValue(gitSectionStorageKey(section), value ? "true" : "false")
   }
 
   createEffect(() => {
@@ -213,28 +264,23 @@ const RightPanel: Component<RightPanelProps> = (props) => {
   })
 
   createEffect(() => {
-    if (typeof window === "undefined") return
-    window.localStorage.setItem(RIGHT_PANEL_TAB_STORAGE_KEY, rightPanelTab())
+    writeClientLayoutValue(RIGHT_PANEL_TAB_STORAGE_KEY, rightPanelTab())
   })
 
   createEffect(() => {
-    if (typeof window === "undefined") return
-    window.localStorage.setItem(RIGHT_PANEL_CHANGES_DIFF_VIEW_MODE_KEY, diffViewMode())
+    writeClientLayoutValue(RIGHT_PANEL_CHANGES_DIFF_VIEW_MODE_KEY, diffViewMode())
   })
 
   createEffect(() => {
-    if (typeof window === "undefined") return
-    window.localStorage.setItem(RIGHT_PANEL_CHANGES_DIFF_CONTEXT_MODE_KEY, diffContextMode())
+    writeClientLayoutValue(RIGHT_PANEL_CHANGES_DIFF_CONTEXT_MODE_KEY, diffContextMode())
   })
 
   createEffect(() => {
-    if (typeof window === "undefined") return
-    window.localStorage.setItem(RIGHT_PANEL_CHANGES_DIFF_WORD_WRAP_KEY, diffWordWrapMode())
+    writeClientLayoutValue(RIGHT_PANEL_CHANGES_DIFF_WORD_WRAP_KEY, diffWordWrapMode())
   })
 
   createEffect(() => {
-    if (typeof window === "undefined") return
-    window.localStorage.setItem(RIGHT_PANEL_FILES_WORD_WRAP_KEY, filesWordWrapMode())
+    writeClientLayoutValue(RIGHT_PANEL_FILES_WORD_WRAP_KEY, filesWordWrapMode())
   })
 
   const clampSplitWidth = (value: number) => {
@@ -255,9 +301,8 @@ const RightPanel: Component<RightPanelProps> = (props) => {
   })
 
   const persistSplitWidth = (mode: "git-changes" | "files", width: number) => {
-    if (typeof window === "undefined") return
     const key = mode === "git-changes" ? RIGHT_PANEL_GIT_CHANGES_SPLIT_WIDTH_KEY : RIGHT_PANEL_FILES_SPLIT_WIDTH_KEY
-    window.localStorage.setItem(key, String(width))
+    writeClientLayoutValue(key, String(width))
   }
 
   function stopSplitResize() {
@@ -655,77 +700,42 @@ const RightPanel: Component<RightPanelProps> = (props) => {
     setRightPanelExpandedItems(values)
   }
 
-  const tabClass = (tab: RightPanelTab) =>
-    `right-panel-tab ${rightPanelTab() === tab ? "right-panel-tab-active" : "right-panel-tab-inactive"}`
+  const updateRightPanelCustomization = (updater: (current: RightPanelCustomization) => RightPanelCustomization) => {
+    const next = updater(rightPanelCustomization())
+    setRightPanelCustomization(next)
+    writeClientLayoutValue(RIGHT_PANEL_CUSTOMIZATION_STORAGE_KEY, JSON.stringify(next))
+  }
 
-  return (
-    <div class="flex flex-col h-full" ref={props.setContentEl}>
-      <div class="right-panel-tab-bar">
-        <div class="tab-container">
-          <div class="tab-strip-shortcuts text-primary">
-            <Show when={props.rightDrawerState() === "floating-open"}>
-              <IconButton
-                size="small"
-                color="inherit"
-                aria-label={props.t("instanceShell.rightDrawer.toggle.close")}
-                title={props.t("instanceShell.rightDrawer.toggle.close")}
-                onClick={props.onCloseRightDrawer}
-              >
-                <MenuOpenIcon fontSize="small" sx={{ transform: "scaleX(-1)" }} />
-              </IconButton>
-            </Show>
-            <Show when={!props.isPhoneLayout()}>
-              <IconButton
-                size="small"
-                color="inherit"
-                aria-label={props.rightPinned() ? props.t("instanceShell.rightDrawer.unpin") : props.t("instanceShell.rightDrawer.pin")}
-                onClick={() => (props.rightPinned() ? props.onUnpinRightDrawer() : props.onPinRightDrawer())}
-              >
-                {props.rightPinned() ? <PushPinIcon fontSize="small" /> : <PushPinOutlinedIcon fontSize="small" />}
-              </IconButton>
-            </Show>
-          </div>
-          <div class="tab-scroll">
-            <div class="tab-strip">
-              <div class="tab-strip-tabs" role="tablist" aria-label={props.t("instanceShell.rightPanel.tabs.ariaLabel")}> 
-                <button
-                  type="button"
-                  role="tab"
-                  class={tabClass("git-changes")}
-                  aria-selected={rightPanelTab() === "git-changes"}
-                  onClick={() => setRightPanelTab("git-changes")}
-                >
-                  <span class="tab-label">{props.t("instanceShell.rightPanel.tabs.gitChanges")}</span>
-                </button>
-                <button
-                  type="button"
-                  role="tab"
-                  class={tabClass("files")}
-                  aria-selected={rightPanelTab() === "files"}
-                  onClick={() => setRightPanelTab("files")}
-                >
-                  <span class="tab-label">{props.t("instanceShell.rightPanel.tabs.files")}</span>
-                </button>
-                <button
-                  type="button"
-                  role="tab"
-                  class={tabClass("status")}
-                  aria-selected={rightPanelTab() === "status"}
-                  onClick={() => setRightPanelTab("status")}
-                >
-                  <span class="tab-label">{props.t("instanceShell.rightPanel.tabs.status")}</span>
-                </button>
-              </div>
+  const moveTab = (sourceId: string, targetId: string) => {
+    if (!sourceId || sourceId === targetId) return
+    const visibleIds = visibleRightPanelTabs().map((tab) => tab.id)
+    const sourceIndex = visibleIds.indexOf(sourceId)
+    const targetIndex = visibleIds.indexOf(targetId)
+    if (sourceIndex === -1 || targetIndex === -1) return
+    const nextVisibleIds = [...visibleIds]
+    const [moved] = nextVisibleIds.splice(sourceIndex, 1)
+    nextVisibleIds.splice(targetIndex, 0, moved)
+    const allIds = allRightPanelTabs().map((tab) => tab.id)
+    updateRightPanelCustomization((current) => ({
+      ...current,
+      tabOrder: [...nextVisibleIds, ...allIds.filter((id) => !nextVisibleIds.includes(id))],
+    }))
+  }
 
-              <div class="tab-strip-spacer" />
-            </div>
-          </div>
-        </div>
-      </div>
+  const handleTabDragEnd = ({ draggable, droppable }: SolidDndDragEvent) => {
+    if (!droppable) return
+    moveTab(String(draggable.id), String(droppable.id))
+  }
 
-      <div class="flex-1 overflow-y-auto">
-        <Show when={rightPanelTab() === "git-changes"}>
-          <Suspense fallback={<RightPanelTabFallback />}>
+  const rightPanelModules = createMemo<RightPanelModule[]>(() => [
+    {
+      id: "core-right-panel",
+      tabs: [
+        {
+          id: "git-changes",
+          labelKey: "instanceShell.rightPanel.tabs.gitChanges",
+          order: 10,
+          render: () => (
             <LazyGitChangesTab
               t={props.t}
               activeSessionId={props.activeSessionId}
@@ -775,11 +785,13 @@ const RightPanel: Component<RightPanelProps> = (props) => {
               onResizeTouchStart={handleSplitResizeTouchStart("git-changes")}
               isPhoneLayout={props.isPhoneLayout}
             />
-          </Suspense>
-        </Show>
-
-        <Show when={rightPanelTab() === "files"}>
-          <Suspense fallback={<RightPanelTabFallback />}>
+          ),
+        },
+        {
+          id: "files",
+          labelKey: "instanceShell.rightPanel.tabs.files",
+          order: 20,
+          render: () => (
             <LazyFilesTab
               t={props.t}
               browserPath={browserPath}
@@ -808,11 +820,13 @@ const RightPanel: Component<RightPanelProps> = (props) => {
               onResizeTouchStart={handleSplitResizeTouchStart("files")}
               isPhoneLayout={props.isPhoneLayout}
             />
-          </Suspense>
-        </Show>
-
-        <Show when={rightPanelTab() === "status"}>
-          <Suspense fallback={<RightPanelTabFallback />}>
+          ),
+        },
+        {
+          id: "status",
+          labelKey: "instanceShell.rightPanel.tabs.status",
+          order: 30,
+          render: () => (
             <LazyStatusTab
               t={props.t}
               instanceId={props.instanceId}
@@ -826,8 +840,195 @@ const RightPanel: Component<RightPanelProps> = (props) => {
               onTerminateBackgroundProcess={props.onTerminateBackgroundProcess}
               expandedItems={rightPanelExpandedItems}
               onExpandedItemsChange={handleAccordionChange}
+              customization={rightPanelCustomization}
+              onCustomizationChange={updateRightPanelCustomization}
+              extraSections={extraStatusSections()}
             />
-          </Suspense>
+          ),
+        },
+      ],
+    },
+  ])
+
+  const allRightPanelTabs = createMemo(() => collectRightPanelItems<RightPanelTabModule>(rightPanelModules(), "tabs"))
+  const visibleRightPanelTabs = createMemo(() =>
+    applyRightPanelItemCustomization(
+      allRightPanelTabs(),
+      rightPanelCustomization().tabOrder,
+      rightPanelCustomization().hiddenTabIds,
+    ),
+  )
+  const orderedRightPanelTabs = createMemo(() => applyRightPanelItemCustomization(allRightPanelTabs(), rightPanelCustomization().tabOrder, []))
+  const extraStatusSections = createMemo(() => collectRightPanelItems<RightPanelSectionModule>(rightPanelModules(), "statusSections"))
+  const allStatusSections = createMemo(() => [...CORE_STATUS_SECTION_ITEMS, ...extraStatusSections()])
+  const orderedStatusSections = createMemo(() => applyRightPanelItemCustomization(allStatusSections(), rightPanelCustomization().statusSectionOrder, []))
+  const visibleStatusSections = createMemo(() =>
+    applyRightPanelItemCustomization(
+      allStatusSections(),
+      rightPanelCustomization().statusSectionOrder,
+      rightPanelCustomization().hiddenStatusSectionIds,
+    ),
+  )
+  const activeRightPanelTab = createMemo(() => visibleRightPanelTabs().find((tab) => tab.id === rightPanelTab()) ?? visibleRightPanelTabs()[0])
+
+  createEffect(() => {
+    const active = activeRightPanelTab()
+    if (active && active.id !== rightPanelTab()) {
+      setRightPanelTab(active.id)
+    }
+  })
+
+  return (
+    <div class="relative flex flex-col h-full" ref={props.setContentEl}>
+      <div class="right-panel-tab-bar">
+        <div class="tab-container">
+          <div class="tab-strip-shortcuts text-primary">
+            <Show when={props.rightDrawerState() === "floating-open"}>
+              <IconButton
+                size="small"
+                color="inherit"
+                aria-label={props.t("instanceShell.rightDrawer.toggle.close")}
+                title={props.t("instanceShell.rightDrawer.toggle.close")}
+                onClick={props.onCloseRightDrawer}
+              >
+                <MenuOpenIcon fontSize="small" sx={{ transform: "scaleX(-1)" }} />
+              </IconButton>
+            </Show>
+            <Show when={!props.isPhoneLayout()}>
+              <IconButton
+                size="small"
+                color="inherit"
+                aria-label={props.rightPinned() ? props.t("instanceShell.rightDrawer.unpin") : props.t("instanceShell.rightDrawer.pin")}
+                onClick={() => (props.rightPinned() ? props.onUnpinRightDrawer() : props.onPinRightDrawer())}
+              >
+                {props.rightPinned() ? <PushPinIcon fontSize="small" /> : <PushPinOutlinedIcon fontSize="small" />}
+              </IconButton>
+            </Show>
+            <IconButton
+              size="small"
+              color="inherit"
+              aria-label={props.t("instanceShell.rightPanel.customize.toggle")}
+              title={props.t("instanceShell.rightPanel.customize.toggle")}
+              aria-expanded={rightPanelCustomizationOpen()}
+              onClick={() => setRightPanelCustomizationOpen((open) => !open)}
+            >
+              <Settings2 class="h-4 w-4" />
+            </IconButton>
+          </div>
+          <div class="tab-scroll">
+            <div class="tab-strip">
+              <div class="tab-strip-tabs" role="tablist" aria-label={props.t("instanceShell.rightPanel.tabs.ariaLabel")}>
+                <DragDropProvider collisionDetector={closestCenter} onDragEnd={handleTabDragEnd}>
+                  <DragDropSensors>
+                    <SortableProvider ids={visibleRightPanelTabs().map((tab) => tab.id)}>
+                      <For each={visibleRightPanelTabs()}>
+                        {(tab) => (
+                          <SortableRightPanelTab
+                            tab={tab}
+                            active={rightPanelTab() === tab.id}
+                            label={props.t(tab.labelKey)}
+                            dragTitle={props.t("instanceShell.rightPanel.customize.dragToReorder")}
+                            onSelect={() => setRightPanelTab(tab.id)}
+                          />
+                        )}
+                      </For>
+                    </SortableProvider>
+                  </DragDropSensors>
+                </DragDropProvider>
+              </div>
+
+              <div class="tab-strip-spacer" />
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <Show when={rightPanelCustomizationOpen()}>
+        <div class="right-panel-customization-popover" role="dialog" aria-label={props.t("instanceShell.rightPanel.customize.title")}>
+          <div class="right-panel-customization-header">
+            <div>
+              <div class="text-sm font-medium text-primary">{props.t("instanceShell.rightPanel.customize.title")}</div>
+              <div class="text-xs text-secondary">{props.t("instanceShell.rightPanel.customize.description")}</div>
+            </div>
+            <button
+              type="button"
+              class="right-panel-customization-button"
+              onClick={() => updateRightPanelCustomization(() => parseRightPanelCustomization(null))}
+            >
+              {props.t("instanceShell.rightPanel.customize.reset")}
+            </button>
+          </div>
+
+          <div class="right-panel-customization-grid">
+            <div class="right-panel-customization-group">
+              <div class="right-panel-customization-group-title">{props.t("instanceShell.rightPanel.customize.tabs")}</div>
+              <For each={orderedRightPanelTabs()}>
+                {(tab) => {
+                  const label = () => props.t(tab.labelKey)
+                  const visible = () => !rightPanelCustomization().hiddenTabIds.includes(tab.id)
+                  const disableHide = () => visible() && visibleRightPanelTabs().length <= 1
+                  return (
+                    <div class="right-panel-customization-row">
+                      <label class="right-panel-customization-label">
+                        <input
+                          type="checkbox"
+                          checked={visible()}
+                          disabled={disableHide()}
+                          onChange={(event) =>
+                            updateRightPanelCustomization((current) => ({
+                              ...current,
+                              hiddenTabIds: setRightPanelItemHidden(current.hiddenTabIds, tab.id, !event.currentTarget.checked),
+                            }))
+                          }
+                        />
+                        <span>{label()}</span>
+                      </label>
+                    </div>
+                  )
+                }}
+              </For>
+            </div>
+
+            <div class="right-panel-customization-group">
+              <div class="right-panel-customization-group-title">{props.t("instanceShell.rightPanel.customize.statusSections")}</div>
+              <For each={orderedStatusSections()}>
+                {(section) => {
+                  const label = () => props.t(section.labelKey)
+                  const visible = () => !rightPanelCustomization().hiddenStatusSectionIds.includes(section.id)
+                  const disableHide = () => visible() && visibleStatusSections().length <= 1
+                  return (
+                    <div class="right-panel-customization-row">
+                      <label class="right-panel-customization-label">
+                        <input
+                          type="checkbox"
+                          checked={visible()}
+                          disabled={disableHide()}
+                          onChange={(event) =>
+                            updateRightPanelCustomization((current) => ({
+                              ...current,
+                              hiddenStatusSectionIds: setRightPanelItemHidden(
+                                current.hiddenStatusSectionIds,
+                                section.id,
+                                !event.currentTarget.checked,
+                              ),
+                            }))
+                          }
+                        />
+                        <span>{label()}</span>
+                      </label>
+                    </div>
+                  )
+                }}
+              </For>
+            </div>
+          </div>
+          <div class="right-panel-customization-hint">{props.t("instanceShell.rightPanel.customize.dragToReorder")}</div>
+        </div>
+      </Show>
+
+      <div class="flex-1 overflow-y-auto">
+        <Show keyed when={activeRightPanelTab()}>
+          {(tab) => <Suspense fallback={<RightPanelTabFallback />}>{tab.render()}</Suspense>}
         </Show>
       </div>
     </div>
diff --git a/packages/ui/src/components/instance/shell/right-panel/registry.test.ts b/packages/ui/src/components/instance/shell/right-panel/registry.test.ts
new file mode 100644
index 00000000..a7b39d01
--- /dev/null
+++ b/packages/ui/src/components/instance/shell/right-panel/registry.test.ts
@@ -0,0 +1,71 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import {
+  applyRightPanelItemCustomization,
+  collectRightPanelItems,
+  moveRightPanelItem,
+  parseRightPanelCustomization,
+  setRightPanelItemHidden,
+  type RightPanelItem,
+  type RightPanelTabModule,
+} from "./registry"
+
+const item = (id: string, order: number, alwaysVisible = false): RightPanelItem => ({ id, labelKey: id, order, alwaysVisible })
+const tab = (id: string, order: number): RightPanelTabModule => ({ ...item(id, order), render: () => undefined as any })
+
+describe("right panel registry", () => {
+  it("collects and orders module items", () => {
+    const items = collectRightPanelItems(
+      [
+        { id: "core", tabs: [tab("status", 40), tab("changes", 10)] },
+        { id: "plugin", tabs: [tab("custom", 30)] },
+      ],
+      "tabs",
+    )
+
+    assert.deepEqual(items.map((entry) => entry.id), ["changes", "custom", "status"])
+  })
+
+  it("rejects duplicate item ids", () => {
+    assert.throws(() => collectRightPanelItems([{ id: "core", tabs: [tab("status", 10), tab("status", 20)] }], "tabs"))
+  })
+
+  it("applies visibility and user order", () => {
+    const visible = applyRightPanelItemCustomization(
+      [item("changes", 10), item("files", 20), item("status", 30)],
+      ["status", "changes"],
+      ["files"],
+    )
+
+    assert.deepEqual(visible.map((entry) => entry.id), ["status", "changes"])
+  })
+
+  it("keeps always-visible items visible", () => {
+    const visible = applyRightPanelItemCustomization([item("configure", 100, true)], [], ["configure"])
+
+    assert.deepEqual(visible.map((entry) => entry.id), ["configure"])
+  })
+
+  it("moves items in normalized order", () => {
+    assert.deepEqual(moveRightPanelItem(["changes", "status", "files"], ["changes", "files", "status"], "status", -1), [
+      "status",
+      "changes",
+      "files",
+    ])
+  })
+
+  it("parses invalid customization safely", () => {
+    assert.deepEqual(parseRightPanelCustomization("{"), {
+      tabOrder: [],
+      hiddenTabIds: [],
+      statusSectionOrder: [],
+      hiddenStatusSectionIds: [],
+    })
+  })
+
+  it("toggles hidden ids", () => {
+    assert.deepEqual(setRightPanelItemHidden(["files"], "status", true), ["files", "status"])
+    assert.deepEqual(setRightPanelItemHidden(["files"], "files", false), [])
+  })
+})
diff --git a/packages/ui/src/components/instance/shell/right-panel/registry.ts b/packages/ui/src/components/instance/shell/right-panel/registry.ts
new file mode 100644
index 00000000..c24077ea
--- /dev/null
+++ b/packages/ui/src/components/instance/shell/right-panel/registry.ts
@@ -0,0 +1,113 @@
+import type { JSX } from "solid-js"
+
+export interface RightPanelItem {
+  id: string
+  labelKey: string
+  order: number
+  alwaysVisible?: boolean
+}
+
+export interface RightPanelTabModule extends RightPanelItem {
+  render: () => JSX.Element
+}
+
+export interface RightPanelSectionModule extends RightPanelItem {
+  tooltipKey: string
+  defaultExpanded?: boolean
+  render: () => JSX.Element
+}
+
+export interface RightPanelModule {
+  id: string
+  tabs?: readonly RightPanelTabModule[]
+  statusSections?: readonly RightPanelSectionModule[]
+}
+
+export interface RightPanelCustomization {
+  tabOrder: string[]
+  hiddenTabIds: string[]
+  statusSectionOrder: string[]
+  hiddenStatusSectionIds: string[]
+}
+
+export const DEFAULT_RIGHT_PANEL_CUSTOMIZATION: RightPanelCustomization = {
+  tabOrder: [],
+  hiddenTabIds: [],
+  statusSectionOrder: [],
+  hiddenStatusSectionIds: [],
+}
+
+export function parseRightPanelCustomization(value: string | null): RightPanelCustomization {
+  if (!value) return { ...DEFAULT_RIGHT_PANEL_CUSTOMIZATION }
+  try {
+    const parsed = JSON.parse(value) as Partial<RightPanelCustomization>
+    return {
+      tabOrder: readStringArray(parsed.tabOrder),
+      hiddenTabIds: readStringArray(parsed.hiddenTabIds),
+      statusSectionOrder: readStringArray(parsed.statusSectionOrder),
+      hiddenStatusSectionIds: readStringArray(parsed.hiddenStatusSectionIds),
+    }
+  } catch {
+    return { ...DEFAULT_RIGHT_PANEL_CUSTOMIZATION }
+  }
+}
+
+export function collectRightPanelItems<T extends RightPanelItem>(modules: readonly RightPanelModule[], key: "tabs" | "statusSections"): T[] {
+  const items = modules.flatMap((module) => [...((module[key] ?? []) as unknown as readonly T[])])
+  const seen = new Set<string>()
+  for (const item of items) {
+    if (!item.id) throw new Error(`Right panel ${key} must define an id`)
+    if (seen.has(item.id)) throw new Error(`Duplicate right panel ${key} id: ${item.id}`)
+    seen.add(item.id)
+  }
+  return sortRightPanelItems(items, [])
+}
+
+export function applyRightPanelItemCustomization<T extends RightPanelItem>(
+  items: readonly T[],
+  orderedIds: readonly string[],
+  hiddenIds: readonly string[],
+): T[] {
+  const hidden = new Set(hiddenIds)
+  const visible = items.filter((item) => item.alwaysVisible || !hidden.has(item.id))
+  return sortRightPanelItems(visible.length > 0 ? visible : items.slice(0, 1), orderedIds)
+}
+
+export function moveRightPanelItem(orderedIds: readonly string[], allIds: readonly string[], id: string, direction: -1 | 1): string[] {
+  const order = normalizeOrder(orderedIds, allIds)
+  const index = order.indexOf(id)
+  const nextIndex = index + direction
+  if (index === -1 || nextIndex < 0 || nextIndex >= order.length) return order
+  const next = [...order]
+  ;[next[index], next[nextIndex]] = [next[nextIndex], next[index]]
+  return next
+}
+
+export function setRightPanelItemHidden(hiddenIds: readonly string[], id: string, hidden: boolean): string[] {
+  const next = new Set(hiddenIds)
+  if (hidden) next.add(id)
+  else next.delete(id)
+  return [...next]
+}
+
+function sortRightPanelItems<T extends RightPanelItem>(items: readonly T[], orderedIds: readonly string[]): T[] {
+  const rank = new Map(orderedIds.map((id, index) => [id, index]))
+  return [...items].sort((left, right) => {
+    const leftRank = rank.get(left.id)
+    const rightRank = rank.get(right.id)
+    if (leftRank !== undefined || rightRank !== undefined) {
+      return (leftRank ?? Number.MAX_SAFE_INTEGER) - (rightRank ?? Number.MAX_SAFE_INTEGER)
+    }
+    return left.order - right.order || left.id.localeCompare(right.id)
+  })
+}
+
+function normalizeOrder(orderedIds: readonly string[], allIds: readonly string[]): string[] {
+  const known = new Set(allIds)
+  const ordered = orderedIds.filter((id, index) => known.has(id) && orderedIds.indexOf(id) === index)
+  return [...ordered, ...allIds.filter((id) => !ordered.includes(id))]
+}
+
+function readStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : []
+}
diff --git a/packages/ui/src/components/instance/shell/right-panel/tabs/StatusTab.tsx b/packages/ui/src/components/instance/shell/right-panel/tabs/StatusTab.tsx
index 8dca954c..84baefd1 100644
--- a/packages/ui/src/components/instance/shell/right-panel/tabs/StatusTab.tsx
+++ b/packages/ui/src/components/instance/shell/right-panel/tabs/StatusTab.tsx
@@ -1,20 +1,30 @@
-import { For, Show, type Accessor, type Component } from "solid-js"
+import { For, Show, createMemo, type Accessor, type Component } from "solid-js"
 import type { ToolState } from "@opencode-ai/sdk/v2"
+import {
+  DragDropProvider,
+  DragDropSensors,
+  SortableProvider,
+  closestCenter,
+  createSortable,
+  type DragEvent as SolidDndDragEvent,
+} from "@thisbeyond/solid-dnd"
 import { Accordion } from "@kobalte/core"
 import { Tooltip } from "@kobalte/core/tooltip"
 import Switch from "@suid/material/Switch"
 
-import { BellRing, ChevronDown, Info, TerminalSquare, Trash2, XOctagon } from "lucide-solid"
+import { BellRing, ChevronDown, GripVertical, Info, TerminalSquare, Trash2, XOctagon } from "lucide-solid"
 
 import type { Instance } from "../../../../../types/instance"
 import type { BackgroundProcess } from "../../../../../../../server/src/api-types"
 import type { Session } from "../../../../../types/session"
 
 import ContextUsagePanel from "../../../../session/context-usage-panel"
+import ProviderUsagePanel from "../../../../session/provider-usage-panel"
 import { TodoListView } from "../../../../tool-call/renderers/todo"
 import InstanceServiceStatus from "../../../../instance-service-status"
 import { togglePermissionAutoAcceptForSession } from "../../../../../stores/instances"
 import { isPermissionAutoAcceptEnabled } from "../../../../../stores/permission-auto-accept"
+import { applyRightPanelItemCustomization, type RightPanelCustomization, type RightPanelSectionModule } from "../registry"
 
 interface StatusTabProps {
   t: (key: string, vars?: Record<string, any>) => string
@@ -34,7 +44,43 @@ interface StatusTabProps {
 
   expandedItems: Accessor<string[]>
   onExpandedItemsChange: (values: string[]) => void
+  customization: Accessor<RightPanelCustomization>
+  onCustomizationChange: (updater: (current: RightPanelCustomization) => RightPanelCustomization) => void
+  extraSections?: readonly RightPanelSectionModule[]
+}
 
+interface SortableStatusSectionProps {
+  section: RightPanelSectionModule
+  expanded: boolean
+  t: (key: string, vars?: Record<string, any>) => string
+}
+
+const SortableStatusSection: Component<SortableStatusSectionProps> = (props) => {
+  const sortable = createSortable(props.section.id)
+  return (
+    <div ref={sortable} class={`right-panel-section-draggable ${sortable.isActiveDraggable ? "right-panel-section-draggable-active" : ""}`}>
+      <Accordion.Item value={props.section.id} class="right-panel-accordion-item">
+        <Accordion.Header class="right-panel-accordion-header-row">
+          <Accordion.Trigger class="right-panel-accordion-trigger">
+            <span class="section-left">
+              <GripVertical class="h-3.5 w-3.5 text-tertiary" aria-hidden="true" />
+              <span class="section-label">{props.t(props.section.labelKey)}</span>
+            </span>
+            <ChevronDown class={`right-panel-accordion-chevron ${props.expanded ? "right-panel-accordion-chevron-expanded" : ""}`} />
+          </Accordion.Trigger>
+          <Tooltip openDelay={200} gutter={4} placement="top">
+            <Tooltip.Trigger as="button" type="button" class="section-info-trigger" aria-label={props.t(props.section.tooltipKey)}>
+              <Info class="section-info-icon" />
+            </Tooltip.Trigger>
+            <Tooltip.Portal>
+              <Tooltip.Content class="section-info-tooltip">{props.t(props.section.tooltipKey)}</Tooltip.Content>
+            </Tooltip.Portal>
+          </Tooltip>
+        </Accordion.Header>
+        <Accordion.Content class="right-panel-accordion-content">{props.section.render()}</Accordion.Content>
+      </Accordion.Item>
+    </div>
+  )
 }
 
 const StatusTab: Component<StatusTabProps> = (props) => {
@@ -51,12 +97,9 @@ const StatusTab: Component<StatusTabProps> = (props) => {
     }
 
     return (
-      <div class="rounded-md border border-base bg-surface-secondary px-3 py-2">
-        <div class="flex items-start justify-between gap-3">
-          <div class="min-w-0">
-            <div class="text-sm font-medium text-primary">{props.t("instanceShell.yoloMode.title")}</div>
-            <p class="mt-1 text-xs text-secondary">{props.t("instanceShell.yoloMode.description")}</p>
-          </div>
+      <div class="flex items-center justify-between gap-2 border border-base bg-surface-secondary px-3 py-2">
+        <p class="min-w-0 text-xs leading-5 text-secondary">{props.t("instanceShell.yoloMode.description")}</p>
+        <div class="-mr-2 shrink-0">
           <Switch
             checked={isPermissionAutoAcceptEnabled(props.instanceId, session.id)}
             color="warning"
@@ -172,65 +215,95 @@ const StatusTab: Component<StatusTabProps> = (props) => {
     )
   }
 
-  const statusSections = [
-    {
-      id: "yolo-mode",
-      labelKey: "instanceShell.rightPanel.sections.yoloMode",
-      tooltipKey: "instanceShell.rightPanel.sections.yoloMode.tooltip",
-      render: renderYoloModeSection,
-    },
-    {
-      id: "plan",
-      labelKey: "instanceShell.rightPanel.sections.plan",
-      tooltipKey: "instanceShell.rightPanel.sections.plan.tooltip",
-      render: renderPlanSectionContent,
-    },
-    {
-      id: "background-processes",
-      labelKey: "instanceShell.rightPanel.sections.backgroundProcesses",
-      tooltipKey: "instanceShell.rightPanel.sections.backgroundProcesses.tooltip",
-      render: renderBackgroundProcesses,
-    },
-    {
-      id: "mcp",
-      labelKey: "instanceShell.rightPanel.sections.mcp",
-      tooltipKey: "instanceShell.rightPanel.sections.mcp.tooltip",
-      render: () => (
-        <InstanceServiceStatus
-          initialInstance={props.instance}
-          sections={["mcp"]}
-          showSectionHeadings={false}
-          class="space-y-2"
-        />
-      ),
-    },
-    {
-      id: "lsp",
-      labelKey: "instanceShell.rightPanel.sections.lsp",
-      tooltipKey: "instanceShell.rightPanel.sections.lsp.tooltip",
-      render: () => (
-        <InstanceServiceStatus
-          initialInstance={props.instance}
-          sections={["lsp"]}
-          showSectionHeadings={false}
-          class="space-y-2"
-        />
-      ),
-    },
-    {
-      id: "plugins",
-      labelKey: "instanceShell.rightPanel.sections.plugins",
-      tooltipKey: "instanceShell.rightPanel.sections.plugins.tooltip",
-      render: () => (
-        <InstanceServiceStatus
-          initialInstance={props.instance}
-          sections={["plugins"]}
-          showSectionHeadings={false}
-          class="space-y-2"
-        />
-      ),
-    },
-  ]
+  const renderProviderUsage = () => {
+    const session = props.activeSession()
+    if (!session) {
+      return <div class="text-xs text-tertiary">{props.t("providerUsage.noSession")}</div>
+    }
+    return (
+      <div class="border border-base bg-surface-secondary px-3 py-2">
+        <ProviderUsagePanel providerId={session.model.providerId} modelId={session.model.modelId} />
+      </div>
+    )
+  }
+
+  const statusSections = createMemo<RightPanelSectionModule[]>(() => {
+    const sections: RightPanelSectionModule[] = [
+      {
+        id: "yolo-mode",
+        labelKey: "instanceShell.rightPanel.sections.yoloMode",
+        tooltipKey: "instanceShell.rightPanel.sections.yoloMode.tooltip",
+        order: 10,
+        render: renderYoloModeSection,
+      },
+      {
+        id: "provider-usage",
+        labelKey: "providerUsage.title",
+        tooltipKey: "providerUsage.tooltip",
+        order: 20,
+        render: renderProviderUsage,
+      },
+      {
+        id: "plan",
+        labelKey: "instanceShell.rightPanel.sections.plan",
+        tooltipKey: "instanceShell.rightPanel.sections.plan.tooltip",
+        order: 30,
+        render: renderPlanSectionContent,
+      },
+      {
+        id: "background-processes",
+        labelKey: "instanceShell.rightPanel.sections.backgroundProcesses",
+        tooltipKey: "instanceShell.rightPanel.sections.backgroundProcesses.tooltip",
+        order: 40,
+        render: renderBackgroundProcesses,
+      },
+      {
+        id: "mcp",
+        labelKey: "instanceShell.rightPanel.sections.mcp",
+        tooltipKey: "instanceShell.rightPanel.sections.mcp.tooltip",
+        order: 50,
+        render: () => <InstanceServiceStatus initialInstance={props.instance} sections={["mcp"]} showSectionHeadings={false} class="space-y-2" />,
+      },
+      {
+        id: "lsp",
+        labelKey: "instanceShell.rightPanel.sections.lsp",
+        tooltipKey: "instanceShell.rightPanel.sections.lsp.tooltip",
+        order: 60,
+        render: () => <InstanceServiceStatus initialInstance={props.instance} sections={["lsp"]} showSectionHeadings={false} class="space-y-2" />,
+      },
+      {
+        id: "plugins",
+        labelKey: "instanceShell.rightPanel.sections.plugins",
+        tooltipKey: "instanceShell.rightPanel.sections.plugins.tooltip",
+        order: 70,
+        render: () => (
+          <InstanceServiceStatus initialInstance={props.instance} sections={["plugins"]} showSectionHeadings={false} class="space-y-2" />
+        ),
+      },
+    ]
+    return applyRightPanelItemCustomization(
+      [...sections, ...(props.extraSections ?? [])],
+      props.customization().statusSectionOrder,
+      props.customization().hiddenStatusSectionIds,
+    )
+  })
+
+  const moveSection = (sourceId: string, targetId: string) => {
+    if (!sourceId || sourceId === targetId) return
+    const ids = statusSections().map((section) => section.id)
+    const sourceIndex = ids.indexOf(sourceId)
+    const targetIndex = ids.indexOf(targetId)
+    if (sourceIndex === -1 || targetIndex === -1) return
+    const next = [...ids]
+    const [moved] = next.splice(sourceIndex, 1)
+    next.splice(targetIndex, 0, moved)
+    props.onCustomizationChange((current) => ({ ...current, statusSectionOrder: next }))
+  }
+
+  const handleSectionDragEnd = ({ draggable, droppable }: SolidDndDragEvent) => {
+    if (!droppable) return
+    moveSection(String(draggable.id), String(droppable.id))
+  }
 
   return (
     <div class="status-tab-container">
@@ -247,31 +320,15 @@ const StatusTab: Component<StatusTabProps> = (props) => {
         value={props.expandedItems()}
         onChange={props.onExpandedItemsChange}
       >
-        <For each={statusSections}>
-          {(section) => (
-            <Accordion.Item value={section.id} class="right-panel-accordion-item">
-              <Accordion.Header class="right-panel-accordion-header-row">
-                <Accordion.Trigger class="right-panel-accordion-trigger">
-                  <span class="section-left">
-                    <span class="section-label">{props.t(section.labelKey)}</span>
-                  </span>
-                  <ChevronDown
-                    class={`right-panel-accordion-chevron ${isSectionExpanded(section.id) ? "right-panel-accordion-chevron-expanded" : ""}`}
-                  />
-                </Accordion.Trigger>
-                <Tooltip openDelay={200} gutter={4} placement="top">
-                  <Tooltip.Trigger as="button" type="button" class="section-info-trigger" aria-label={props.t(section.tooltipKey)}>
-                    <Info class="section-info-icon" />
-                  </Tooltip.Trigger>
-                  <Tooltip.Portal>
-                    <Tooltip.Content class="section-info-tooltip">{props.t(section.tooltipKey)}</Tooltip.Content>
-                  </Tooltip.Portal>
-                </Tooltip>
-              </Accordion.Header>
-              <Accordion.Content class="right-panel-accordion-content">{section.render()}</Accordion.Content>
-            </Accordion.Item>
-          )}
-        </For>
+        <DragDropProvider collisionDetector={closestCenter} onDragEnd={handleSectionDragEnd}>
+          <DragDropSensors>
+            <SortableProvider ids={statusSections().map((section) => section.id)}>
+              <For each={statusSections()}>
+                {(section) => <SortableStatusSection section={section} expanded={isSectionExpanded(section.id)} t={props.t} />}
+              </For>
+            </SortableProvider>
+          </DragDropSensors>
+        </DragDropProvider>
       </Accordion.Root>
     </div>
   )
diff --git a/packages/ui/src/components/instance/shell/right-panel/tabs/status-sections.ts b/packages/ui/src/components/instance/shell/right-panel/tabs/status-sections.ts
new file mode 100644
index 00000000..87933d77
--- /dev/null
+++ b/packages/ui/src/components/instance/shell/right-panel/tabs/status-sections.ts
@@ -0,0 +1,46 @@
+import type { RightPanelItem } from "../registry"
+
+export const CORE_STATUS_SECTION_ITEMS: readonly (RightPanelItem & { tooltipKey: string; defaultExpanded?: boolean })[] = [
+  {
+    id: "yolo-mode",
+    labelKey: "instanceShell.rightPanel.sections.yoloMode",
+    tooltipKey: "instanceShell.rightPanel.sections.yoloMode.tooltip",
+    order: 10,
+  },
+  {
+    id: "provider-usage",
+    labelKey: "providerUsage.title",
+    tooltipKey: "providerUsage.tooltip",
+    order: 20,
+  },
+  {
+    id: "plan",
+    labelKey: "instanceShell.rightPanel.sections.plan",
+    tooltipKey: "instanceShell.rightPanel.sections.plan.tooltip",
+    order: 30,
+  },
+  {
+    id: "background-processes",
+    labelKey: "instanceShell.rightPanel.sections.backgroundProcesses",
+    tooltipKey: "instanceShell.rightPanel.sections.backgroundProcesses.tooltip",
+    order: 40,
+  },
+  {
+    id: "mcp",
+    labelKey: "instanceShell.rightPanel.sections.mcp",
+    tooltipKey: "instanceShell.rightPanel.sections.mcp.tooltip",
+    order: 50,
+  },
+  {
+    id: "lsp",
+    labelKey: "instanceShell.rightPanel.sections.lsp",
+    tooltipKey: "instanceShell.rightPanel.sections.lsp.tooltip",
+    order: 60,
+  },
+  {
+    id: "plugins",
+    labelKey: "instanceShell.rightPanel.sections.plugins",
+    tooltipKey: "instanceShell.rightPanel.sections.plugins.tooltip",
+    order: 70,
+  },
+]
diff --git a/packages/ui/src/components/instance/shell/right-panel/types.ts b/packages/ui/src/components/instance/shell/right-panel/types.ts
index aa407b6e..e24e3b46 100644
--- a/packages/ui/src/components/instance/shell/right-panel/types.ts
+++ b/packages/ui/src/components/instance/shell/right-panel/types.ts
@@ -1,4 +1,4 @@
-export type RightPanelTab = "git-changes" | "files" | "status"
+export type RightPanelTab = string
 
 export type DiffViewMode = "split" | "unified"
 
@@ -27,7 +27,7 @@ export type GitChangeSection = "staged" | "unstaged"
 export interface GitChangeListItem {
   id: string
   path: string
-   originalPath?: string | null
+  originalPath?: string | null
   section: GitChangeSection
   status: GitChangeStatus
   additions: number
diff --git a/packages/ui/src/components/instance/shell/storage.ts b/packages/ui/src/components/instance/shell/storage.ts
index f50b5f4c..0e685d4e 100644
--- a/packages/ui/src/components/instance/shell/storage.ts
+++ b/packages/ui/src/components/instance/shell/storage.ts
@@ -1,3 +1,5 @@
+import { readClientLayoutValue, writeClientLayoutValue } from "../../../stores/client-state"
+
 export const DEFAULT_SESSION_SIDEBAR_WIDTH = 340
 export const MIN_SESSION_SIDEBAR_WIDTH = 220
 export const MAX_SESSION_SIDEBAR_WIDTH = 400
@@ -10,8 +12,11 @@ export const LEFT_DRAWER_STORAGE_KEY = "opencode-session-sidebar-width-v8"
 export const RIGHT_DRAWER_STORAGE_KEY = "opencode-session-right-drawer-width-v1"
 export const LEFT_PIN_STORAGE_KEY = "opencode-session-left-drawer-pinned-v1"
 export const RIGHT_PIN_STORAGE_KEY = "opencode-session-right-drawer-pinned-v1"
+export const LEFT_OPEN_STORAGE_KEY = "opencode-session-left-drawer-open-v1"
+export const RIGHT_OPEN_STORAGE_KEY = "opencode-session-right-drawer-open-v1"
 export const RIGHT_PANEL_TAB_STORAGE_KEY = "opencode-session-right-panel-tab-v2"
 export const LEGACY_RIGHT_PANEL_TAB_STORAGE_KEY = "opencode-session-right-panel-tab-v1"
+export const RIGHT_PANEL_CUSTOMIZATION_STORAGE_KEY = "opencode-session-right-panel-customization-v1"
 export const RIGHT_PANEL_FILES_SPLIT_WIDTH_KEY = "opencode-session-right-panel-files-split-width-v1"
 export const RIGHT_PANEL_GIT_CHANGES_SPLIT_WIDTH_KEY = "opencode-session-right-panel-git-changes-split-width-v1"
 export const RIGHT_PANEL_FILES_LIST_OPEN_NONPHONE_KEY = "opencode-session-right-panel-files-list-open-nonphone-v1"
@@ -37,33 +42,40 @@ export const clampRightWidth = (value: number) => {
 }
 
 const getPinStorageKey = (side: "left" | "right") => (side === "left" ? LEFT_PIN_STORAGE_KEY : RIGHT_PIN_STORAGE_KEY)
+const getOpenStorageKey = (side: "left" | "right") => (side === "left" ? LEFT_OPEN_STORAGE_KEY : RIGHT_OPEN_STORAGE_KEY)
 
 export function readStoredPinState(side: "left" | "right", defaultValue: boolean) {
-  if (typeof window === "undefined") return defaultValue
-  const stored = window.localStorage.getItem(getPinStorageKey(side))
+  const stored = readClientLayoutValue(getPinStorageKey(side))
   if (stored === "true") return true
   if (stored === "false") return false
   return defaultValue
 }
 
 export function persistPinState(side: "left" | "right", value: boolean) {
-  if (typeof window === "undefined") return
-  window.localStorage.setItem(getPinStorageKey(side), value ? "true" : "false")
+  writeClientLayoutValue(getPinStorageKey(side), value ? "true" : "false")
 }
 
-export function readStoredRightPanelTab(
-  defaultValue: "git-changes" | "files" | "status",
-): "git-changes" | "files" | "status" {
-  if (typeof window === "undefined") return defaultValue
+export function readStoredOpenState(side: "left" | "right", defaultValue: boolean) {
+  const stored = readClientLayoutValue(getOpenStorageKey(side))
+  if (stored === "true") return true
+  if (stored === "false") return false
+  return defaultValue
+}
 
-  const stored = window.localStorage.getItem(RIGHT_PANEL_TAB_STORAGE_KEY)
+export function persistOpenState(side: "left" | "right", value: boolean) {
+  writeClientLayoutValue(getOpenStorageKey(side), value ? "true" : "false")
+}
+
+export function readStoredRightPanelTab(defaultValue: string): string {
+  const stored = readClientLayoutValue(RIGHT_PANEL_TAB_STORAGE_KEY)
   if (stored === "status") return "status"
   if (stored === "changes") return "git-changes"
   if (stored === "git-changes") return "git-changes"
   if (stored === "files") return "files"
+  if (stored) return stored
 
   // Migrate from v1 (where the stored values were the internal tab ids).
-  const legacy = window.localStorage.getItem(LEGACY_RIGHT_PANEL_TAB_STORAGE_KEY)
+  const legacy = readClientLayoutValue(LEGACY_RIGHT_PANEL_TAB_STORAGE_KEY)
   if (legacy === "status") return "status"
   if (legacy === "browser") return "files"
   if (legacy === "files") return "git-changes"
@@ -72,24 +84,21 @@ export function readStoredRightPanelTab(
 }
 
 export function readStoredPanelWidth(key: string, fallback: number) {
-  if (typeof window === "undefined") return fallback
-  const stored = window.localStorage.getItem(key)
+  const stored = readClientLayoutValue(key)
   if (!stored) return fallback
   const parsed = Number.parseInt(stored, 10)
   return Number.isFinite(parsed) ? parsed : fallback
 }
 
 export function readStoredBool(key: string): boolean | null {
-  if (typeof window === "undefined") return null
-  const stored = window.localStorage.getItem(key)
+  const stored = readClientLayoutValue(key)
   if (stored === "true") return true
   if (stored === "false") return false
   return null
 }
 
 export function readStoredEnum<T extends string>(key: string, allowed: readonly T[]): T | null {
-  if (typeof window === "undefined") return null
-  const stored = window.localStorage.getItem(key)
+  const stored = readClientLayoutValue(key)
   if (!stored) return null
   return (allowed as readonly string[]).includes(stored) ? (stored as T) : null
 }
diff --git a/packages/ui/src/components/instance/shell/useDrawerChrome.ts b/packages/ui/src/components/instance/shell/useDrawerChrome.ts
index 4b123817..49235e55 100644
--- a/packages/ui/src/components/instance/shell/useDrawerChrome.ts
+++ b/packages/ui/src/components/instance/shell/useDrawerChrome.ts
@@ -15,10 +15,11 @@ import MenuIcon from "@suid/icons-material/Menu"
 import type { TranslateParams } from "../../../lib/i18n"
 
 import type { DrawerViewState, LayoutMode } from "./types"
-import { persistPinState, readStoredPinState } from "./storage"
+import { persistOpenState, persistPinState, readStoredOpenState, readStoredPinState } from "./storage"
 
 export interface UseDrawerChromeOptions {
   t: (key: string, params?: TranslateParams) => string
+  active: Accessor<boolean>
   layoutMode: Accessor<LayoutMode>
   leftPinningSupported: Accessor<boolean>
   rightPinningSupported: Accessor<boolean>
@@ -88,9 +89,9 @@ export function useDrawerChrome(options: UseDrawerChromeOptions): DrawerChromeAp
         const leftSaved = readStoredPinState("left", true)
         const rightSaved = readStoredPinState("right", true)
         setLeftPinned(leftSaved)
-        setLeftOpen(leftSaved)
+        setLeftOpen(leftSaved || readStoredOpenState("left", false))
         setRightPinned(rightSaved)
-        setRightOpen(rightSaved)
+        setRightOpen(rightSaved || readStoredOpenState("right", false))
         break
       }
       case "tablet": {
@@ -109,6 +110,12 @@ export function useDrawerChrome(options: UseDrawerChromeOptions): DrawerChromeAp
     }
   })
 
+  createEffect(() => {
+    if (options.layoutMode() !== "desktop" || !options.active()) return
+    persistOpenState("left", leftOpen())
+    persistOpenState("right", rightOpen())
+  })
+
   const leftDrawerState = createMemo<DrawerViewState>(() => {
     if (leftPinned()) return "pinned"
     return leftOpen() ? "floating-open" : "floating-closed"
diff --git a/packages/ui/src/components/instance/shell/useInstanceSessionContext.ts b/packages/ui/src/components/instance/shell/useInstanceSessionContext.ts
index 9b84ba86..3544ac48 100644
--- a/packages/ui/src/components/instance/shell/useInstanceSessionContext.ts
+++ b/packages/ui/src/components/instance/shell/useInstanceSessionContext.ts
@@ -1,4 +1,4 @@
-import { batch, createMemo, type Accessor } from "solid-js"
+import { createMemo, type Accessor } from "solid-js"
 import type { ToolState } from "@opencode-ai/sdk/v2"
 import type { Session } from "../../../types/session"
 import {
@@ -8,8 +8,8 @@ import {
   getSessionInfo,
   getSessionThreads,
   sessions,
-  setActiveParentSession,
   setActiveSession,
+  setActiveSessionFromList,
 } from "../../../stores/sessions"
 import { messageStoreBus } from "../../../stores/message-v2/bus"
 import { getBackgroundProcesses } from "../../../stores/background-processes"
@@ -131,21 +131,8 @@ export function useInstanceSessionContext(options: InstanceSessionContextOptions
       return
     }
 
-    const session = allInstanceSessions().get(sessionId)
-    if (!session) return
-
-    if (session.parentId === null) {
-      setActiveParentSession(instanceId, sessionId)
-      return
-    }
-
-    const parentId = session.parentId
-    if (!parentId) return
-
-    batch(() => {
-      setActiveParentSession(instanceId, parentId)
-      setActiveSession(instanceId, sessionId)
-    })
+    if (!allInstanceSessions().has(sessionId)) return
+    setActiveSessionFromList(instanceId, sessionId)
   }
 
   return {
diff --git a/packages/ui/src/components/instance/shell/useSessionCache.ts b/packages/ui/src/components/instance/shell/useSessionCache.ts
index 0e3a3476..35ffe5c7 100644
--- a/packages/ui/src/components/instance/shell/useSessionCache.ts
+++ b/packages/ui/src/components/instance/shell/useSessionCache.ts
@@ -2,6 +2,7 @@ import { createEffect, createSignal, type Accessor } from "solid-js"
 import { messageStoreBus } from "../../../stores/message-v2/bus"
 import { clearSessionRenderCache } from "../../message-block"
 import { getLogger } from "../../../lib/logger"
+import { invalidateSessionMessageLoad } from "../../../stores/session-state"
 
 const log = getLogger("session")
 
@@ -26,7 +27,8 @@ export function useSessionCache(options: SessionCacheOptions): SessionCacheState
     const instanceId = options.instanceId()
     log.info("Evicting cached session", { instanceId, sessionId })
     const store = messageStoreBus.getInstance(instanceId)
-    store?.clearSession(sessionId)
+    invalidateSessionMessageLoad(instanceId, sessionId)
+    store?.clearSession(sessionId, { preserveScroll: true, notify: false })
     clearSessionRenderCache(instanceId, sessionId)
   }
 
diff --git a/packages/ui/src/components/load-error-state.tsx b/packages/ui/src/components/load-error-state.tsx
new file mode 100644
index 00000000..9da704d7
--- /dev/null
+++ b/packages/ui/src/components/load-error-state.tsx
@@ -0,0 +1,40 @@
+import type { Component } from "solid-js"
+import { AlertTriangle } from "lucide-solid"
+
+interface LoadErrorStateProps {
+  title: string
+  error: string
+  retryLabel: string
+  onRetry: () => void
+  variant?: "compact" | "panel"
+}
+
+const LoadErrorState: Component<LoadErrorStateProps> = (props) => {
+  const content = (
+    <div class={props.variant === "compact" ? "flex items-start gap-2" : "flex flex-col items-center text-center"}>
+      <AlertTriangle
+        class={props.variant === "compact" ? "mt-0.5 h-4 w-4 flex-shrink-0 text-danger" : "mb-3 h-6 w-6 text-danger"}
+        aria-hidden="true"
+      />
+      <div class="min-w-0 flex-1">
+        <h3 class="text-sm font-medium text-danger">{props.title}</h3>
+        <p class="mt-2 break-words text-xs leading-5 text-muted">{props.error}</p>
+        <button type="button" class="button-tertiary mt-3" onClick={props.onRetry}>
+          {props.retryLabel}
+        </button>
+      </div>
+    </div>
+  )
+
+  if (props.variant === "compact") {
+    return <div class="m-3 border border-danger bg-danger/10 p-3" role="alert">{content}</div>
+  }
+
+  return (
+    <div class="flex flex-1 items-center justify-center p-12" role="alert">
+      <div class="w-full max-w-md border border-danger bg-danger/10 p-6">{content}</div>
+    </div>
+  )
+}
+
+export default LoadErrorState
diff --git a/packages/ui/src/components/locale-selector.tsx b/packages/ui/src/components/locale-selector.tsx
new file mode 100644
index 00000000..a935eaf6
--- /dev/null
+++ b/packages/ui/src/components/locale-selector.tsx
@@ -0,0 +1,69 @@
+import { Select } from "@kobalte/core/select"
+import { ChevronDown, Languages } from "lucide-solid"
+import type { Component } from "solid-js"
+import { useI18n, type Locale } from "../lib/i18n"
+import { useConfig } from "../stores/preferences"
+
+type LanguageOption = { value: Locale; label: string }
+
+const languageOptions: LanguageOption[] = [
+  { value: "en", label: "English" },
+  { value: "es", label: "Español" },
+  { value: "fr", label: "Français" },
+  { value: "ru", label: "Русский" },
+  { value: "ja", label: "日本語" },
+  { value: "zh-Hans", label: "简体中文" },
+  { value: "he", label: "עברית" },
+  { value: "de", label: "Deutsch" },
+  { value: "ne", label: "नेपाली" },
+]
+
+export const LocaleSelector: Component = () => {
+  const { t, locale } = useI18n()
+  const { updatePreferences } = useConfig()
+  const selectedOption = () => languageOptions.find((option) => option.value === locale()) ?? languageOptions[0]
+
+  return (
+    <Select<LanguageOption>
+      value={selectedOption()}
+      onChange={(option) => {
+        if (!option || option.value === locale()) return
+        updatePreferences({ locale: option.value })
+      }}
+      options={languageOptions}
+      optionValue="value"
+      optionTextValue="label"
+      itemComponent={(itemProps) => (
+        <Select.Item item={itemProps.item} class="selector-option">
+          <Select.ItemLabel class="selector-option-label">{itemProps.item.rawValue.label}</Select.ItemLabel>
+        </Select.Item>
+      )}
+    >
+      <Select.Trigger
+        class="selector-trigger"
+        aria-label={t("folderSelection.language.ariaLabel")}
+        title={t("folderSelection.language.ariaLabel")}
+      >
+        <Languages class="w-4 h-4 icon-muted" aria-hidden="true" />
+        <div class="flex-1 min-w-0">
+          <Select.Value<LanguageOption>>
+            {(state) => (
+              <span class="selector-trigger-primary selector-trigger-primary--align-left">
+                {state.selectedOption()?.label}
+              </span>
+            )}
+          </Select.Value>
+        </div>
+        <Select.Icon class="selector-trigger-icon">
+          <ChevronDown class="w-3 h-3" />
+        </Select.Icon>
+      </Select.Trigger>
+
+      <Select.Portal>
+        <Select.Content class="selector-popover min-w-[180px]">
+          <Select.Listbox class="selector-listbox" />
+        </Select.Content>
+      </Select.Portal>
+    </Select>
+  )
+}
diff --git a/packages/ui/src/components/markdown.tsx b/packages/ui/src/components/markdown.tsx
index 4ec0c5d7..91d40793 100644
--- a/packages/ui/src/components/markdown.tsx
+++ b/packages/ui/src/components/markdown.tsx
@@ -15,6 +15,7 @@ interface ResolvedMarkdownSnapshot {
   themeKey: string
   highlightEnabled: boolean
   escapeRawHtml: boolean
+  defaultCodeBlockWrap: boolean
   partId: string | undefined
   cacheId: string
   version: string
@@ -96,6 +97,7 @@ interface MarkdownProps {
   size?: "base" | "sm" | "tight"
   disableHighlight?: boolean
   escapeRawHtml?: boolean
+  defaultCodeBlockWrap?: boolean
   onRendered?: () => void
 }
 
@@ -105,11 +107,54 @@ export function Markdown(props: MarkdownProps) {
   let containerRef: HTMLDivElement | undefined
   let latestRequestKey = ""
   let cleanupLanguageListener: (() => void) | undefined
+  const codeBlockWrapOverrides = new Map<string, boolean>()
 
   const notifyRendered = () => {
     Promise.resolve().then(() => props.onRendered?.())
   }
 
+  const codeBlockWrapKey = (codeBlock: HTMLElement): string | null => {
+    const key = codeBlock.getAttribute("data-code-block-key")
+    if (!key) {
+      return null
+    }
+    return `${resolved().cacheId}:${key}`
+  }
+
+  const applyCodeBlockWrapState = (codeBlock: HTMLElement, enabled: boolean) => {
+    codeBlock.setAttribute("data-wrap-lines", enabled ? "true" : "false")
+
+    const button = codeBlock.querySelector<HTMLButtonElement>(".code-block-wrap")
+    if (!button) {
+      return
+    }
+
+    const label = enabled ? t("markdown.codeBlock.wrap.disable") : t("markdown.codeBlock.wrap.enable")
+    button.classList.toggle("active", enabled)
+    button.setAttribute("aria-pressed", enabled ? "true" : "false")
+    button.setAttribute("aria-label", label)
+    button.setAttribute("title", label)
+
+    const text = button.querySelector(".wrap-text")
+    if (text) {
+      text.textContent = label
+    }
+  }
+
+  const syncCodeBlockWrapStates = () => {
+    if (!containerRef) {
+      return
+    }
+
+    const codeBlocks = containerRef.querySelectorAll<HTMLElement>(".markdown-code-block")
+    for (const codeBlock of codeBlocks) {
+      const key = codeBlockWrapKey(codeBlock)
+      const defaultEnabled = codeBlock.getAttribute("data-wrap-lines") !== "false"
+      const enabled = key ? (codeBlockWrapOverrides.get(key) ?? defaultEnabled) : defaultEnabled
+      applyCodeBlockWrapState(codeBlock, enabled)
+    }
+  }
+
   const resolved = createMemo(() => {
     const part = props.part
     const rawText = typeof part.text === "string" ? part.text : ""
@@ -117,11 +162,23 @@ export function Markdown(props: MarkdownProps) {
     const themeKey = Boolean(props.isDark) ? "dark" : "light"
     const highlightEnabled = !props.disableHighlight
     const escapeRawHtml = Boolean(props.escapeRawHtml)
+    const defaultCodeBlockWrap = props.defaultCodeBlockWrap ?? true
     const partId = typeof part.id === "string" && part.id.length > 0 ? part.id : undefined
     const cacheId = resolvePartCacheId(part, text)
     const version = resolvePartVersion(part, text)
-    const requestKey = `${cacheId}:${themeKey}:${highlightEnabled ? 1 : 0}:${escapeRawHtml ? 1 : 0}:${version}`
-    return { part, text, themeKey, highlightEnabled, escapeRawHtml, partId, cacheId, version, requestKey }
+    const requestKey = `${cacheId}:${themeKey}:${highlightEnabled ? 1 : 0}:${escapeRawHtml ? 1 : 0}:${defaultCodeBlockWrap ? 1 : 0}:${version}`
+    return {
+      part,
+      text,
+      themeKey,
+      highlightEnabled,
+      escapeRawHtml,
+      defaultCodeBlockWrap,
+      partId,
+      cacheId,
+      version,
+      requestKey,
+    }
   })
 
   const cacheHandle = useGlobalCache({
@@ -129,8 +186,8 @@ export function Markdown(props: MarkdownProps) {
     sessionId: () => props.sessionId,
     scope: "markdown",
     cacheId: () => {
-      const { cacheId, themeKey, highlightEnabled } = resolved()
-      return `${cacheId}:${themeKey}:${highlightEnabled ? 1 : 0}:${resolved().escapeRawHtml ? 1 : 0}`
+      const { cacheId, themeKey, highlightEnabled, escapeRawHtml, defaultCodeBlockWrap } = resolved()
+      return `${cacheId}:${themeKey}:${highlightEnabled ? 1 : 0}:${escapeRawHtml ? 1 : 0}:${defaultCodeBlockWrap ? 1 : 0}`
     },
     version: () => resolved().version,
   })
@@ -144,7 +201,7 @@ export function Markdown(props: MarkdownProps) {
       text: snapshot.text,
       html: renderedHtml,
       theme: snapshot.themeKey,
-      mode: `${snapshot.version}:${snapshot.escapeRawHtml ? "escaped" : "raw"}`,
+      mode: `${snapshot.version}:${snapshot.escapeRawHtml ? "escaped" : "raw"}:${snapshot.defaultCodeBlockWrap ? "wrap" : "nowrap"}`,
     }
     setHtml(renderedHtml)
     if (options?.cache ?? true) {
@@ -159,6 +216,7 @@ export function Markdown(props: MarkdownProps) {
     const rendered = await markdown.renderMarkdown(snapshot.text, {
       suppressHighlight: !snapshot.highlightEnabled,
       escapeRawHtml: snapshot.escapeRawHtml,
+      defaultCodeBlockWrap: snapshot.defaultCodeBlockWrap,
     })
     const shouldCache = !snapshot.highlightEnabled || !markdown.hasPendingCodeHighlight(snapshot.text)
 
@@ -170,7 +228,7 @@ export function Markdown(props: MarkdownProps) {
   createEffect(() => {
     const snapshot = resolved()
     latestRequestKey = snapshot.requestKey
-    const cacheMode = `${snapshot.version}:${snapshot.escapeRawHtml ? "escaped" : "raw"}`
+    const cacheMode = `${snapshot.version}:${snapshot.escapeRawHtml ? "escaped" : "raw"}:${snapshot.defaultCodeBlockWrap ? "wrap" : "nowrap"}`
 
     const cacheMatches = (cache: RenderCache | undefined) => {
       if (!cache) return false
@@ -202,9 +260,33 @@ export function Markdown(props: MarkdownProps) {
     })
   })
 
+  createEffect(() => {
+    html()
+    Promise.resolve().then(syncCodeBlockWrapStates)
+  })
+
   onMount(() => {
     const handleClick = async (event: Event) => {
       const target = event.target as HTMLElement
+      const wrapButton = target.closest(".code-block-wrap") as HTMLButtonElement
+      if (wrapButton) {
+        event.preventDefault()
+        const codeBlock = wrapButton.closest(".markdown-code-block") as HTMLElement | null
+        if (!codeBlock) {
+          return
+        }
+
+        const key = codeBlockWrapKey(codeBlock)
+        const current = codeBlock.getAttribute("data-wrap-lines") !== "false"
+        const next = !current
+        if (key) {
+          codeBlockWrapOverrides.set(key, next)
+        }
+        applyCodeBlockWrapState(codeBlock, next)
+        props.onRendered?.()
+        return
+      }
+
       const copyButton = target.closest(".code-block-copy") as HTMLButtonElement
 
       if (!copyButton) {
diff --git a/packages/ui/src/components/message-block.tsx b/packages/ui/src/components/message-block.tsx
index fa705335..cc3691ac 100644
--- a/packages/ui/src/components/message-block.tsx
+++ b/packages/ui/src/components/message-block.tsx
@@ -8,7 +8,7 @@ import { buildRecordDisplayData, clearRecordDisplayCacheForInstance } from "../s
 import type { MessageRecord } from "../stores/message-v2/types"
 import { messageStoreBus } from "../stores/message-v2/bus"
 import { formatTokenTotal } from "../lib/formatters"
-import { sessions, setActiveParentSession, setActiveSession } from "../stores/sessions"
+import { ensureSessionAncestorsExpanded, sessions, setActiveSessionFromList } from "../stores/sessions"
 import { selectInstanceTab } from "../stores/app-tabs"
 import { showAlertDialog } from "../stores/alerts"
 import { deleteMessage } from "../stores/session-actions"
@@ -21,6 +21,7 @@ import type { SessionSearchMatch } from "../lib/session-search"
 import ActionOverflowMenu, { type ActionOverflowMenuItem } from "./action-overflow-menu"
 import { copyToClipboard } from "../lib/clipboard"
 import SpeechActionButton from "./speech-action-button"
+import type { VisibilityPreference } from "../stores/preferences"
 
 function DeleteUpToIcon() {
   return (
@@ -33,7 +34,6 @@ function DeleteUpToIcon() {
 const USER_BORDER_COLOR = "var(--message-user-border)"
 const ASSISTANT_BORDER_COLOR = "var(--message-assistant-border)"
 const NO_STEP_BORDER = "none"
-const REASONING_SCROLL_SENTINEL_MARGIN_PX = 48
 
 const LazyToolCall = lazy(() => import("./tool-call"))
 
@@ -136,11 +136,8 @@ function findTaskSessionLocation(sessionId: string, preferredInstanceId?: string
 
 function navigateToTaskSession(location: TaskSessionLocation) {
   selectInstanceTab(location.instanceId)
-  const parentToActivate = location.parentId ?? location.sessionId
-  setActiveParentSession(location.instanceId, parentToActivate)
-  if (location.parentId) {
-    setActiveSession(location.instanceId, location.sessionId)
-  }
+  ensureSessionAncestorsExpanded(location.instanceId, location.sessionId)
+  setActiveSessionFromList(location.instanceId, location.sessionId)
 }
 
 interface CachedBlockEntry {
@@ -637,11 +634,13 @@ interface MessageBlockProps {
   lastAssistantIndex: () => number
   showThinking: () => boolean
   thinkingDefaultExpanded: () => boolean
-  showUsageMetrics: () => boolean
+  usageMetricsVisibility: () => VisibilityPreference
+  toolVisibility: (toolName: string) => VisibilityPreference
   deleteHover?: () => DeleteHoverState
   onDeleteHoverChange?: (state: DeleteHoverState) => void
   selectedMessageIds?: () => Set<string>
   selectedToolPartKeys?: () => Set<string>
+  selectedCompanionPartKeys?: () => Set<string>
   onToggleSelectedMessage?: (messageId: string, selected: boolean) => void
   onRevert?: (messageId: string) => void
   onDeleteMessagesUpTo?: (messageId: string) => void | Promise<void>
@@ -661,8 +660,7 @@ export default function MessageBlock(props: MessageBlockProps) {
   const isDeleteMessageHovered = () => {
     const hover = props.deleteHover?.() ?? ({ kind: "none" } as DeleteHoverState)
 
-    const selected = props.selectedMessageIds?.() ?? new Set<string>()
-    if (selected.has(props.messageId)) {
+    if (props.selectedMessageIds?.().has(props.messageId)) {
       return true
     }
 
@@ -724,7 +722,7 @@ export default function MessageBlock(props: MessageBlockProps) {
       isQueued ? 1 : 0,
       props.showThinking() ? 1 : 0,
       props.thinkingDefaultExpanded() ? 1 : 0,
-      props.showUsageMetrics() ? 1 : 0,
+      props.usageMetricsVisibility(),
     ].join("|")
 
     const cachedBlock = sessionCache.messageBlocks.get(current.id)
@@ -832,7 +830,7 @@ export default function MessageBlock(props: MessageBlockProps) {
 
       if (part.type === "step-finish") {
         flushContent()
-        if (props.showUsageMetrics()) {
+        if (props.usageMetricsVisibility() !== "hidden") {
           const key = `${current.id}:${part.id ?? partIndex}:${part.type}`
           const accentColor = lastAccentColor || defaultAccentColor
           items.push({ type: part.type, key, part, messageInfo: info, accentColor })
@@ -894,9 +892,23 @@ export default function MessageBlock(props: MessageBlockProps) {
     return resultBlock
   })
 
+  const isDisplayItemVisible = (item: MessageBlockItem) => {
+    if (item.type !== "tool") return true
+    const part = props.store().getMessage(item.messageId)?.parts[item.partId]?.data
+    if (part?.type !== "tool" || props.toolVisibility(part.tool || "") !== "hidden") return true
+    return Boolean(
+      part.pendingPermission?.active ||
+      props.store().getPermissionState(item.messageId, item.partId)?.active ||
+      props.store().getQuestionState(item.messageId, item.partId)?.active,
+    )
+  }
+
+  const firstVisibleItemIndex = () => (block()?.items ?? []).findIndex(isDisplayItemVisible)
+
   return (
     <Show when={block()}>
       {(resolvedBlock) => (
+        <Show when={resolvedBlock().items.some(isDisplayItemVisible)}>
         <div
           ref={(el) => {
             blockRef = el
@@ -919,7 +931,7 @@ export default function MessageBlock(props: MessageBlockProps) {
                     startPartId={(item() as ContentDisplayItem).startPartId}
                     messageIndex={props.messageIndex}
                     lastAssistantIndex={props.lastAssistantIndex}
-                    showDeleteMessage={index === 0}
+                    showDeleteMessage={index === firstVisibleItemIndex()}
                     onDeleteHoverChange={props.onDeleteHoverChange}
                     onRevert={props.onRevert}
                     onDeleteMessagesUpTo={props.onDeleteMessagesUpTo}
@@ -933,6 +945,7 @@ export default function MessageBlock(props: MessageBlockProps) {
                   {(() => {
                     const toolItem = item() as ToolDisplayItem
                     return (
+                      <Show when={isDisplayItemVisible(toolItem)}>
                       <div class="tool-call-message" data-key={toolItem.key} data-part-id={toolItem.partId}>
                           <ToolCallItem
                             instanceId={props.instanceId}
@@ -940,7 +953,7 @@ export default function MessageBlock(props: MessageBlockProps) {
                             store={props.store}
                             messageId={toolItem.messageId}
                             partId={toolItem.partId}
-                            showDeleteMessage={index === 0}
+                            showDeleteMessage={index === firstVisibleItemIndex()}
                           deleteHover={props.deleteHover}
                           onDeleteHoverChange={props.onDeleteHoverChange}
                           onDeleteMessagesUpTo={props.onDeleteMessagesUpTo}
@@ -950,6 +963,7 @@ export default function MessageBlock(props: MessageBlockProps) {
                           onContentRendered={props.onContentRendered}
                         />
                       </div>
+                      </Show>
                     )
                   })()}
                 </Match>
@@ -959,13 +973,14 @@ export default function MessageBlock(props: MessageBlockProps) {
                     part={(item() as StepDisplayItem).part}
                     messageInfo={(item() as StepDisplayItem).messageInfo}
                     showAgentMeta
-                    showDeleteMessage={index === 0}
+                    showDeleteMessage={index === firstVisibleItemIndex()}
                     instanceId={props.instanceId}
                     sessionId={props.sessionId}
                     messageId={props.messageId}
                     onDeleteHoverChange={props.onDeleteHoverChange}
                     onDeleteMessagesUpTo={props.onDeleteMessagesUpTo}
                     selectedMessageIds={props.selectedMessageIds}
+                    selectedCompanionPartKeys={props.selectedCompanionPartKeys}
                     onToggleSelectedMessage={props.onToggleSelectedMessage}
                   />
                 </Match>
@@ -974,15 +989,16 @@ export default function MessageBlock(props: MessageBlockProps) {
                     kind="finish"
                     part={(item() as StepDisplayItem).part}
                     messageInfo={(item() as StepDisplayItem).messageInfo}
-                    showUsage={props.showUsageMetrics()}
+                    usageVisibility={props.usageMetricsVisibility()}
                     borderColor={(item() as StepDisplayItem).accentColor}
-                    showDeleteMessage={index === 0}
+                    showDeleteMessage={index === firstVisibleItemIndex()}
                     instanceId={props.instanceId}
                     sessionId={props.sessionId}
                     messageId={props.messageId}
                     onDeleteHoverChange={props.onDeleteHoverChange}
                     onDeleteMessagesUpTo={props.onDeleteMessagesUpTo}
                     selectedMessageIds={props.selectedMessageIds}
+                    selectedCompanionPartKeys={props.selectedCompanionPartKeys}
                     onToggleSelectedMessage={props.onToggleSelectedMessage}
                     onContentRendered={props.onContentRendered}
                   />
@@ -995,7 +1011,7 @@ export default function MessageBlock(props: MessageBlockProps) {
                     instanceId={props.instanceId}
                     sessionId={props.sessionId}
                     messageId={(item() as CompactionDisplayItem).messageId}
-                    showDeleteMessage={index === 0}
+                    showDeleteMessage={index === firstVisibleItemIndex()}
                     onDeleteHoverChange={props.onDeleteHoverChange}
                     onDeleteMessagesUpTo={props.onDeleteMessagesUpTo}
                     selectedMessageIds={props.selectedMessageIds}
@@ -1012,10 +1028,11 @@ export default function MessageBlock(props: MessageBlockProps) {
                     messageId={(item() as ReasoningDisplayItem).messageId}
                     showAgentMeta={(item() as ReasoningDisplayItem).showAgentMeta}
                     defaultExpanded={(item() as ReasoningDisplayItem).defaultExpanded}
-                    showDeleteMessage={index === 0}
+                    showDeleteMessage={index === firstVisibleItemIndex()}
                     onDeleteHoverChange={props.onDeleteHoverChange}
                     onDeleteMessagesUpTo={props.onDeleteMessagesUpTo}
                     selectedMessageIds={props.selectedMessageIds}
+                    selectedCompanionPartKeys={props.selectedCompanionPartKeys}
                     onToggleSelectedMessage={props.onToggleSelectedMessage}
                     onContentRendered={props.onContentRendered}
                     forceExpanded={activeSearchMatch()?.partId === (item() as ReasoningDisplayItem).partId}
@@ -1025,6 +1042,7 @@ export default function MessageBlock(props: MessageBlockProps) {
             )}
           </Index>
         </div>
+        </Show>
       )}
     </Show>
   )
@@ -1035,7 +1053,7 @@ interface StepCardProps {
   part: ClientPart
   messageInfo?: MessageInfo
   showAgentMeta?: boolean
-  showUsage?: boolean
+  usageVisibility?: VisibilityPreference
   borderColor?: string
   showDeleteMessage?: boolean
   instanceId?: string
@@ -1044,6 +1062,7 @@ interface StepCardProps {
   onDeleteHoverChange?: (state: DeleteHoverState) => void
   onDeleteMessagesUpTo?: (messageId: string) => void | Promise<void>
   selectedMessageIds?: () => Set<string>
+  selectedCompanionPartKeys?: () => Set<string>
   onToggleSelectedMessage?: (messageId: string, selected: boolean) => void
   onContentRendered?: () => void
 }
@@ -1171,7 +1190,24 @@ function StepCard(props: StepCardProps) {
   const { t } = useI18n()
   const [deletingMessage, setDeletingMessage] = createSignal(false)
   const [deletingUpTo, setDeletingUpTo] = createSignal(false)
+  const [usageExpandedOverride, setUsageExpandedOverride] = createSignal<boolean | null>(null)
+  const usageExpanded = () => usageExpandedOverride() ?? props.usageVisibility === "expanded"
+  let usagePartId = (props.part as { id?: string }).id
+  createEffect(() => {
+    const nextPartId = (props.part as { id?: string }).id
+    if (nextPartId === usagePartId) return
+    usagePartId = nextPartId
+    setUsageExpandedOverride(null)
+  })
   const isSelectedForDeletion = () => Boolean(props.messageId && props.selectedMessageIds?.().has(props.messageId))
+  const isSelectedCompanion = () => {
+    const partId = (props.part as { id?: unknown })?.id
+    return Boolean(
+      props.messageId &&
+      typeof partId === "string" &&
+      props.selectedCompanionPartKeys?.().has(`${props.messageId}:${partId}`),
+    )
+  }
   const timestamp = () => {
     const value = props.messageInfo?.time?.created ?? (props.part as any)?.time?.start ?? Date.now()
     const date = new Date(value)
@@ -1196,12 +1232,12 @@ function StepCard(props: StepCardProps) {
   }
 
   const usageStats = () => {
-    if (props.kind !== "finish" || !props.showUsage) {
+    if (props.kind !== "finish" || props.usageVisibility === "hidden") {
       return null
     }
     const info = props.messageInfo
     const part = props.part as any
-    
+
     // step-finish parts have tokens embedded; also check messageInfo
     const partTokens = part?.tokens
     const infoTokens = info && info.role === "assistant" ? info.tokens : undefined
@@ -1209,7 +1245,7 @@ function StepCard(props: StepCardProps) {
     if (!tokens) {
       return null
     }
-    
+
     return {
       input: tokens.input ?? 0,
       output: tokens.output ?? 0,
@@ -1307,16 +1343,22 @@ function StepCard(props: StepCardProps) {
   }
 
 
-  const renderUsageChips = (usage: NonNullable<ReturnType<typeof usageStats>>) => {
-    const entries = [
+  const usageEntries = (usage: NonNullable<ReturnType<typeof usageStats>>) => [
       { label: t("messageBlock.usage.input"), value: usage.input, formatter: formatTokenTotal },
       { label: t("messageBlock.usage.output"), value: usage.output, formatter: formatTokenTotal },
-      { label: t("messageBlock.usage.reasoning"), value: usage.reasoning, formatter: formatTokenTotal },
-      { label: t("messageBlock.usage.cacheRead"), value: usage.cacheRead, formatter: formatTokenTotal },
-      { label: t("messageBlock.usage.cacheWrite"), value: usage.cacheWrite, formatter: formatTokenTotal },
+      ...(usageExpanded()
+        ? [
+            { label: t("messageBlock.usage.reasoning"), value: usage.reasoning, formatter: formatTokenTotal },
+            { label: t("messageBlock.usage.cacheRead"), value: usage.cacheRead, formatter: formatTokenTotal },
+            { label: t("messageBlock.usage.cacheWrite"), value: usage.cacheWrite, formatter: formatTokenTotal },
+          ]
+        : []),
       { label: t("messageBlock.usage.cost"), value: usage.cost, formatter: formatCostValue },
     ]
 
+  const renderUsageChips = (usage: NonNullable<ReturnType<typeof usageStats>>) => {
+    const entries = usageEntries(usage)
+
     return (
       <div class="message-step-usage">
         <For each={entries}>
@@ -1336,7 +1378,11 @@ function StepCard(props: StepCardProps) {
       return null
     }
     return (
-      <div class={`message-step-card message-step-finish message-step-finish-flush relative`} style={finishStyle()}>
+      <div
+        class="delete-hover-scope message-step-card message-step-finish message-step-finish-flush relative"
+        style={finishStyle()}
+        data-delete-part-hover={isSelectedCompanion() ? "true" : undefined}
+      >
         <Show when={props.showDeleteMessage}>
           <div class="absolute right-3 top-1/2 -translate-y-1/2 flex items-center gap-1">
             <ActionOverflowMenu
@@ -1348,7 +1394,16 @@ function StepCard(props: StepCardProps) {
           </div>
         </Show>
 
-        {renderUsageChips(usage)}
+        <button
+          type="button"
+          class="message-step-usage-toggle"
+          aria-expanded={usageExpanded()}
+          aria-label={`${t(usageExpanded() ? "messageBlock.usage.collapseAriaLabel" : "messageBlock.usage.expandAriaLabel")}. ${usageEntries(usage).map((entry) => `${entry.label}: ${entry.formatter(entry.value)}`).join(", ")}`}
+          onClick={() => setUsageExpandedOverride((current) => !(current ?? props.usageVisibility === "expanded"))}
+        >
+          <span class="message-step-usage-disclosure" aria-hidden="true">{usageExpanded() ? "▼" : "▶"}</span>
+          {renderUsageChips(usage)}
+        </button>
       </div>
     )
   }
@@ -1401,6 +1456,7 @@ interface ReasoningCardProps {
   onDeleteHoverChange?: (state: DeleteHoverState) => void
   onDeleteMessagesUpTo?: (messageId: string) => void | Promise<void>
   selectedMessageIds?: () => Set<string>
+  selectedCompanionPartKeys?: () => Set<string>
   onToggleSelectedMessage?: (messageId: string, selected: boolean) => void
   onContentRendered?: () => void
   forceExpanded?: boolean
@@ -1419,7 +1475,6 @@ function ReasoningStreamOutput(props: {
   const followScroll = createFollowScroll({
     getScrollTopSnapshot: props.scrollTopSnapshot,
     setScrollTopSnapshot: props.setScrollTopSnapshot,
-    sentinelMarginPx: REASONING_SCROLL_SENTINEL_MARGIN_PX,
     sentinelClassName: "reasoning-scroll-sentinel",
   })
 
@@ -1480,6 +1535,13 @@ function ReasoningCard(props: ReasoningCardProps) {
   const [deletingUpTo, setDeletingUpTo] = createSignal(false)
   const [scrollTopSnapshot, setScrollTopSnapshot] = createSignal(0)
   const isSelectedForDeletion = () => Boolean(props.selectedMessageIds?.().has(props.messageId))
+  const isSelectedCompanion = () => {
+    const partId = (props.part as { id?: unknown })?.id
+    return Boolean(
+      typeof partId === "string" &&
+      props.selectedCompanionPartKeys?.().has(`${props.messageId}:${partId}`),
+    )
+  }
 
   createEffect(() => {
     setExpanded(Boolean(props.defaultExpanded))
@@ -1699,6 +1761,7 @@ function ReasoningCard(props: ReasoningCardProps) {
   return (
     <div
       class="delete-hover-scope message-reasoning-card"
+      data-delete-part-hover={isSelectedCompanion() ? "true" : undefined}
       data-part-id={typeof (props.part as any)?.id === "string" ? (props.part as any).id : undefined}
     >
       <div class="message-reasoning-header">
diff --git a/packages/ui/src/components/message-preview.tsx b/packages/ui/src/components/message-preview.tsx
index fbac99f9..6b7c855e 100644
--- a/packages/ui/src/components/message-preview.tsx
+++ b/packages/ui/src/components/message-preview.tsx
@@ -29,7 +29,8 @@ const MessagePreview: Component<MessagePreviewProps> = (props) => {
         lastAssistantIndex={lastAssistantIndex}
         showThinking={() => false}
         thinkingDefaultExpanded={() => false}
-        showUsageMetrics={() => false}
+        usageMetricsVisibility={() => "hidden"}
+        toolVisibility={() => "expanded"}
         deleteHover={props.deleteHover}
         onDeleteHoverChange={props.onDeleteHoverChange}
         onDeleteMessagesUpTo={props.onDeleteMessagesUpTo}
diff --git a/packages/ui/src/components/message-section.tsx b/packages/ui/src/components/message-section.tsx
index 9492a919..f8030233 100644
--- a/packages/ui/src/components/message-section.tsx
+++ b/packages/ui/src/components/message-section.tsx
@@ -2,11 +2,12 @@ import { Show, createEffect, createMemo, createSignal, onCleanup, on, untrack }
 import { ArrowUpDown, ChevronDown, ChevronUp, MoreHorizontal, Pause, Search, Trash, X } from "lucide-solid"
 import Kbd from "./kbd"
 import BrandedEmptyState from "./branded-empty-state"
+import LoadErrorState from "./load-error-state"
 import MessageBlock from "./message-block"
 import { getMessageAnchorId } from "./message-anchors"
 import MessageTimeline, { buildTimelineSegments, type TimelineSegment } from "./message-timeline"
-import VirtualFollowList, { type VirtualFollowBottomIntent, type VirtualFollowListApi, type VirtualFollowListState, type VirtualFollowScrollSnapshot } from "./virtual-follow-list"
-import { isSnapshotAutoFollowing } from "./virtual-follow-behavior"
+import VirtualFollowList, { type VirtualExplicitBottomPinIntent, type VirtualFollowListApi, type VirtualFollowListState, type VirtualFollowScrollSnapshot } from "./virtual-follow-list"
+import { isScrollRestoreGenerationCurrent, isSnapshotAutoFollowing } from "./virtual-follow-behavior"
 import { useConfig } from "../stores/preferences"
 import { getSessionInfo } from "../stores/sessions"
 import { messageStoreBus } from "../stores/message-v2/bus"
@@ -20,11 +21,12 @@ import type { DeleteHoverState } from "../types/delete-hover"
 import { partHasRenderableText } from "../types/message"
 import { buildRecordDisplayData } from "../stores/message-v2/record-display-cache"
 import { getPartCharCount } from "../lib/token-utils"
+import { getMessageSelectionActionPosition } from "../lib/message-selection-position"
 import { buildSessionSearchMatches } from "../lib/session-search"
 import type { SessionSearchMatch } from "../lib/session-search"
-import { resolveThinkingExpansionDefault } from "./tool-call/tool-registry"
+import { resolveThinkingExpansionDefault, resolveToolVisibility } from "./tool-call/tool-registry"
+import { collectToolDeletionCompanionPartIds, executeBulkDeletionPlan } from "./tool-deletion-companions"
 
-const SCROLL_SENTINEL_MARGIN_PX = 8
 const MESSAGE_SCROLL_CACHE_SCOPE = "message-stream"
 const QUOTE_SELECTION_MAX_LENGTH = 2000
 const STREAMING_TEXT_HOLD_TOP_THRESHOLD_PX = 8
@@ -49,13 +51,15 @@ export interface MessageSectionProps {
   onReloadMessages?: () => void
   isActive?: boolean
   sessionStreamingActive?: boolean
-  bottomFollowIntent?: VirtualFollowBottomIntent | null
+  explicitBottomPinIntent?: VirtualExplicitBottomPinIntent | null
+  onExplicitBottomPinCancelled?: () => void
 }
 
 export default function MessageSection(props: MessageSectionProps) {
   const { preferences, updatePreferences } = useConfig()
   const { t } = useI18n()
-  const showUsagePreference = () => preferences().showUsageMetrics ?? true
+  const usageMetricsVisibility = () =>
+    preferences().showUsageMetrics ? preferences().usageMetricsExpansion : "hidden"
   const showMessageTimelinePreference = () => preferences().showMessageTimeline ?? true
   const showTimelineToolsPreference = () => preferences().showTimelineTools ?? true
   const holdLongAssistantRepliesEnabled = () => preferences().holdLongAssistantReplies ?? true
@@ -119,8 +123,8 @@ export default function MessageSection(props: MessageSectionProps) {
     const pref = preferences()
     const showThinking = pref.showThinkingBlocks ? 1 : 0
     const thinkingExpansion = resolveThinkingExpansionDefault(pref) ? "expanded" : "collapsed"
-    const showUsage = (pref.showUsageMetrics ?? true) ? 1 : 0
-    return `${showThinking}|${thinkingExpansion}|${showUsage}`
+    const usageVisibility = pref.showUsageMetrics ? pref.usageMetricsExpansion : "hidden"
+    return `${showThinking}|${thinkingExpansion}|${usageVisibility}`
   })
 
   const handleTimelineSegmentClick = (segment: TimelineSegment) => {
@@ -502,6 +506,34 @@ export default function MessageSection(props: MessageSectionProps) {
     }
     return set
   })
+  const deleteCompanionParts = createMemo(() => {
+    sessionRevision()
+    const selectedByMessage = new Map<string, Set<string>>()
+    for (const entry of deleteToolParts()) {
+      const selected = selectedByMessage.get(entry.messageId) ?? new Set<string>()
+      selected.add(entry.partId)
+      selectedByMessage.set(entry.messageId, selected)
+    }
+
+    const companions: { messageId: string; partId: string }[] = []
+    const s = store()
+    for (const [messageId, selectedToolPartIds] of selectedByMessage) {
+      const record = s.getMessage(messageId)
+      if (!record) continue
+      const partIds = collectToolDeletionCompanionPartIds(
+        record.partIds ?? [],
+        (partId) => record.parts?.[partId]?.data,
+        selectedToolPartIds,
+      )
+      for (const partId of partIds) {
+        companions.push({ messageId, partId })
+      }
+    }
+    return companions
+  })
+  const deleteCompanionPartKeys = createMemo(() =>
+    new Set(deleteCompanionParts().map((entry) => `${entry.messageId}:${entry.partId}`)),
+  )
   const isDeleteMode = createMemo(() => deleteMessageIds().size > 0 || deleteToolParts().length > 0)
   const selectedDeleteCount = createMemo(() => deleteMessageIds().size + deleteToolParts().length)
 
@@ -551,6 +583,10 @@ export default function MessageSection(props: MessageSectionProps) {
         }
         total += Math.max(Math.round(chars / 4), 1)
       }
+      for (const { messageId, partId } of deleteCompanionParts()) {
+        const part = s.getMessage(messageId)?.parts?.[partId]?.data
+        if (part) total += Math.max(Math.round(getPartCharCount(part) / 4), 1)
+      }
     }
     return total
   })
@@ -628,15 +664,22 @@ export default function MessageSection(props: MessageSectionProps) {
       }
     }
 
+    const companionParts = deleteCompanionParts()
+
     try {
-      for (const messageId of toDelete) {
-        await deleteMessage(props.instanceId, props.sessionId, messageId)
-      }
-      for (const { messageId, partId } of toolParts) {
-        if (!allowed.has(messageId)) continue
-        await deleteMessagePart(props.instanceId, props.sessionId, messageId, partId)
-      }
-      clearDeleteMode()
+      await executeBulkDeletionPlan(
+        {
+          messageIds: toDelete,
+          companionParts: companionParts.filter(({ messageId }) => allowed.has(messageId)),
+          toolParts: toolParts.filter(({ messageId }) => allowed.has(messageId)),
+        },
+        {
+          clearSelection: clearDeleteMode,
+          deleteMessage: (messageId) => deleteMessage(props.instanceId, props.sessionId, messageId),
+          deletePart: ({ messageId, partId }) =>
+            deleteMessagePart(props.instanceId, props.sessionId, messageId, partId),
+        },
+      )
     } catch (error) {
       showAlertDialog(t("messageSection.bulkDelete.failedMessage"), {
         title: t("messageSection.bulkDelete.failedTitle"),
@@ -668,6 +711,7 @@ export default function MessageSection(props: MessageSectionProps) {
   const [didRestoreScroll, setDidRestoreScroll] = createSignal(false)
   const lastGoodScrollSnapshots = new Map<string, VirtualFollowScrollSnapshot>()
   let restoringScrollSnapshot = false
+  let scrollRestoreGeneration = 0
 
   function getLastGoodScrollSnapshot(sessionId: string) {
     return lastGoodScrollSnapshots.get(sessionId) ?? store().getScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE)
@@ -681,6 +725,8 @@ export default function MessageSection(props: MessageSectionProps) {
     on(
       () => props.sessionId,
       () => {
+        scrollRestoreGeneration += 1
+        restoringScrollSnapshot = false
         setDidRestoreScroll(false)
         const snapshot = store().getScrollSnapshot(props.sessionId, MESSAGE_SCROLL_CACHE_SCOPE)
         if (snapshot) setLastGoodScrollSnapshot(props.sessionId, snapshot)
@@ -716,6 +762,7 @@ export default function MessageSection(props: MessageSectionProps) {
 
   function persistMessageScrollSnapshot(options?: { sessionId?: string; allowCapture?: boolean; requireActive?: boolean }) {
     if (restoringScrollSnapshot) return
+    if (!didRestoreScroll()) return
 
     const sessionId = options?.sessionId ?? props.sessionId
     const allowCapture = options?.allowCapture ?? true
@@ -735,16 +782,6 @@ export default function MessageSection(props: MessageSectionProps) {
       return
     }
 
-    const element = streamElement()
-    if (!allowCapture || !canCapture) return
-    if (!element) return
-    const scrollTop = element.scrollTop
-    const maxScrollTop = Math.max(element.scrollHeight - element.clientHeight, 0)
-    const scrollRatio = maxScrollTop > 0 ? scrollTop / maxScrollTop : 0
-    const atBottom = element.scrollHeight - (element.scrollTop + element.clientHeight) <= 48
-    const snapshot = { scrollTop, scrollRatio, maxScrollTop, atBottom }
-    setLastGoodScrollSnapshot(sessionId, snapshot)
-    store().setScrollSnapshot(sessionId, MESSAGE_SCROLL_CACHE_SCOPE, snapshot)
   }
 
   // Persist scroll position when switching sessions. This effect's cleanup runs
@@ -752,7 +789,7 @@ export default function MessageSection(props: MessageSectionProps) {
   createEffect(() => {
     const sessionId = props.sessionId
     onCleanup(() => {
-      persistMessageScrollSnapshot({ sessionId, requireActive: false })
+      persistMessageScrollSnapshot({ sessionId, allowCapture: props.sessionId === sessionId, requireActive: false })
     })
   })
 
@@ -783,7 +820,7 @@ export default function MessageSection(props: MessageSectionProps) {
     setScrollControlsOpen(false)
   }
 
-  function openScrollControlsFromTrigger(event: PointerEvent) {
+  function openScrollControlsFromTrigger(event: MouseEvent) {
     event.preventDefault()
     event.stopPropagation()
     if (scrollControlsOpen()) return
@@ -795,7 +832,7 @@ export default function MessageSection(props: MessageSectionProps) {
     event.preventDefault()
     event.stopPropagation()
     action()
-    setScrollControlsHoverSuppressed(event.pointerType !== "mouse")
+    setScrollControlsHoverSuppressed(false)
     closeScrollControls()
   }
 
@@ -836,7 +873,7 @@ export default function MessageSection(props: MessageSectionProps) {
     const api = listApi()
     if (!api) return
     if (props.registerScrollToBottom) {
-      props.registerScrollToBottom(() => api.scrollToBottom({ immediate: true, suppressHold: true }))
+      props.registerScrollToBottom(() => api.scrollToBottom({ immediate: true }))
       onCleanup(() => props.registerScrollToBottom?.(null))
     }
   })
@@ -859,25 +896,43 @@ export default function MessageSection(props: MessageSectionProps) {
       return
     }
 
+    const restoreSessionId = props.sessionId
+    const restoreGeneration = ++scrollRestoreGeneration
+    const isCurrentRestore = () => isScrollRestoreGenerationCurrent(
+      restoreSessionId,
+      restoreGeneration,
+      props.sessionId,
+      scrollRestoreGeneration,
+    )
     restoringScrollSnapshot = true
     api.restoreScrollSnapshot(snapshot, {
       behavior: "auto",
       fallback: () => {
+        if (!isCurrentRestore()) return
         api.setAutoScroll(true)
         api.scrollToBottom({ immediate: true })
         restoringScrollSnapshot = false
         setDidRestoreScroll(true)
       },
       onApplied: () => {
+        if (!isCurrentRestore()) return
+        restoringScrollSnapshot = false
+        setLastGoodScrollSnapshot(restoreSessionId, snapshot)
+        setDidRestoreScroll(true)
+      },
+      onCancelled: () => {
+        if (!isCurrentRestore()) return
         restoringScrollSnapshot = false
-        setLastGoodScrollSnapshot(props.sessionId, snapshot)
         setDidRestoreScroll(true)
       },
     })
   })
 
   onCleanup(() => {
-    persistMessageScrollSnapshot({ requireActive: false })
+    const allowCapture = !restoringScrollSnapshot
+    scrollRestoreGeneration += 1
+    restoringScrollSnapshot = false
+    persistMessageScrollSnapshot({ allowCapture, requireActive: false })
   })
 
   function clearQuoteSelection() {
@@ -944,15 +999,22 @@ export default function MessageSection(props: MessageSectionProps) {
       clearQuoteSelection()
       return
     }
-    const rects = range.getClientRects()
-    const anchorRect = rects.length > 0 ? rects[0] : range.getBoundingClientRect()
+    const rects = Array.from(range.getClientRects())
+    const fallbackRect = range.getBoundingClientRect()
     const shellRect = shell.getBoundingClientRect()
-    const relativeTop = Math.max(anchorRect.top - shellRect.top - 40, 8)
-    // Keep the popover within the stream shell. The quote popover currently
-    // renders 3 actions; keep enough horizontal room for the pill.
-    const maxLeft = Math.max(shell.clientWidth - 260, 8)
-    const relativeLeft = Math.min(Math.max(anchorRect.left - shellRect.left, 8), maxLeft)
-    setQuoteSelection({ text: limited, top: relativeTop, left: relativeLeft })
+    const touchOnly = Boolean(
+      window.matchMedia?.("(pointer: coarse)")?.matches
+      && !window.matchMedia?.("(any-pointer: fine)")?.matches,
+    )
+    const position = getMessageSelectionActionPosition(
+      rects,
+      fallbackRect,
+      shellRect,
+      shell.clientWidth,
+      shell.clientHeight,
+      touchOnly,
+    )
+    setQuoteSelection({ text: limited, ...position })
   }
 
   function handleStreamMouseUp() {
@@ -1264,7 +1326,7 @@ export default function MessageSection(props: MessageSectionProps) {
     if (!match || !isSearchOpen()) return
     if (match.id === lastScrolledSearchMatchId) return
     lastScrolledSearchMatchId = match.id
-    listApi()?.scrollToKey(match.messageId, { behavior: "smooth", block: "start", setAutoScroll: false })
+    listApi()?.scrollToKey(match.messageId, { behavior: "smooth", block: "start" })
   })
 
 
@@ -1367,8 +1429,6 @@ export default function MessageSection(props: MessageSectionProps) {
           getKey={(messageId) => messageId}
           getAnchorId={getMessageAnchorId}
           overscanPx={800}
-          scrollSentinelMarginPx={SCROLL_SENTINEL_MARGIN_PX}
-          suspendMeasurements={() => !isActive()}
           streamingActive={streamingActive}
           isActive={isActive}
           scrollToBottomOnActivate={() => false}
@@ -1376,7 +1436,8 @@ export default function MessageSection(props: MessageSectionProps) {
           initialAutoScroll={initialAutoScroll}
           resetKey={() => props.sessionId}
           followToken={followToken}
-          forceBottomFollowIntent={() => props.bottomFollowIntent ?? null}
+          explicitBottomPinIntent={() => props.explicitBottomPinIntent ?? null}
+          onExplicitBottomPinCancelled={props.onExplicitBottomPinCancelled}
           autoPinHoldEnabled={holdLongAssistantRepliesEnabled}
           autoPinHoldTargetKey={autoPinHoldTargetKey}
           autoPinHoldTopThresholdPx={STREAMING_TEXT_HOLD_TOP_THRESHOLD_PX}
@@ -1429,7 +1490,7 @@ export default function MessageSection(props: MessageSectionProps) {
               <button
                 type="button"
                 class="message-scroll-button message-scroll-controls-trigger"
-                onPointerUp={openScrollControlsFromTrigger}
+                onClick={openScrollControlsFromTrigger}
                 aria-label={t("messageSection.scroll.showControlsAriaLabel")}
                 title={t("messageSection.scroll.showControlsAriaLabel")}
               >
@@ -1472,7 +1533,7 @@ export default function MessageSection(props: MessageSectionProps) {
                   <button
                     type="button"
                     class="message-scroll-button"
-                    onPointerUp={(event) => runScrollControlAction(event, () => api.scrollToBottom({ suppressHold: true }))}
+                    onPointerUp={(event) => runScrollControlAction(event, () => api.scrollToBottom())}
                     aria-label={t("messageSection.scroll.toLatestAriaLabel")}
                   >
                     <span class="message-scroll-icon" aria-hidden="true">
@@ -1533,15 +1594,12 @@ export default function MessageSection(props: MessageSectionProps) {
 
               <Show when={!props.loading && props.loadError}>
                 {(loadError) => (
-                  <div class="message-load-error-state">
-                    <div class="message-load-error-card">
-                      <h3>{t("messageSection.loadError.title")}</h3>
-                      <p>{loadError()}</p>
-                      <button type="button" class="message-load-error-retry" onClick={() => props.onReloadMessages?.()}>
-                        {t("messageSection.loadError.reload")}
-                      </button>
-                    </div>
-                  </div>
+                  <LoadErrorState
+                    title={t("messageSection.loadError.title")}
+                    error={loadError()}
+                    retryLabel={t("messageSection.loadError.reload")}
+                    onRetry={() => props.onReloadMessages?.()}
+                  />
                 )}
               </Show>
             </>
@@ -1556,11 +1614,13 @@ export default function MessageSection(props: MessageSectionProps) {
               lastAssistantIndex={lastAssistantIndex}
               showThinking={() => preferences().showThinkingBlocks}
               thinkingDefaultExpanded={() => resolveThinkingExpansionDefault(preferences())}
-              showUsageMetrics={showUsagePreference}
+              usageMetricsVisibility={usageMetricsVisibility}
+              toolVisibility={(toolName) => resolveToolVisibility(preferences(), toolName)}
               deleteHover={deleteHover}
               onDeleteHoverChange={setDeleteHover}
               selectedMessageIds={selectedForDeletion}
               selectedToolPartKeys={deleteToolPartKeys}
+              selectedCompanionPartKeys={deleteCompanionPartKeys}
               onToggleSelectedMessage={setMessageSelectedForDeletion}
               onRevert={props.onRevert}
               onDeleteMessagesUpTo={props.onDeleteMessagesUpTo}
diff --git a/packages/ui/src/components/permission-approval-modal.tsx b/packages/ui/src/components/permission-approval-modal.tsx
index d9329286..b2de5f11 100644
--- a/packages/ui/src/components/permission-approval-modal.tsx
+++ b/packages/ui/src/components/permission-approval-modal.tsx
@@ -11,7 +11,7 @@ import {
   getQuestionEnqueuedAtForInstance,
   sendPermissionResponse,
 } from "../stores/instances"
-import { ensureSessionParentExpanded, loadMessages, sessions as sessionStateSessions, setActiveSessionFromList } from "../stores/sessions"
+import { ensureSessionAncestorsExpanded, loadMessages, sessions as sessionStateSessions, setActiveSessionFromList } from "../stores/sessions"
 import { messageStoreBus } from "../stores/message-v2/bus"
 import { PERMISSION_REJECT_REASON_MAX_LENGTH } from "./tool-call/permission-constants"
 
@@ -262,10 +262,8 @@ const PermissionApprovalModal: Component<PermissionApprovalModalProps> = (props)
   function handleGoToSession(sessionId: string) {
     if (!sessionId) return
 
-    const session = sessionStateSessions().get(props.instanceId)?.get(sessionId)
-    const parentId = session?.parentId ?? session?.id
-    if (parentId) {
-      ensureSessionParentExpanded(props.instanceId, parentId)
+    if (sessionStateSessions().get(props.instanceId)?.has(sessionId)) {
+      ensureSessionAncestorsExpanded(props.instanceId, sessionId)
     }
 
     setActiveSessionFromList(props.instanceId, sessionId)
diff --git a/packages/ui/src/components/prompt-input.tsx b/packages/ui/src/components/prompt-input.tsx
index 51320f25..bb6ca60f 100644
--- a/packages/ui/src/components/prompt-input.tsx
+++ b/packages/ui/src/components/prompt-input.tsx
@@ -4,6 +4,7 @@ import ExpandButton from "./expand-button"
 import { clearAttachments, removeAttachment } from "../stores/attachments"
 import { createPastedPlaceholderRegex, pastedDisplayCounterRegex } from "./prompt-input/attachmentPlaceholders"
 import { preparePromptSubmission } from "./prompt-input/submitPrompt"
+import { focusConversationStream } from "./focus-conversation"
 import Kbd from "./kbd"
 import { getActiveInstance } from "../stores/instances"
 import { agents, executeCustomCommand } from "../stores/sessions"
@@ -325,11 +326,6 @@ export default function PromptInput(props: PromptInputProps) {
     ),
   )
 
-  const isCoarsePointer = () => {
-    if (typeof window === "undefined") return false
-    return Boolean(window.matchMedia?.("(pointer: coarse)")?.matches)
-  }
-
   const isTouchOnlyPointer = () => {
     if (typeof window === "undefined") return false
     return Boolean(window.matchMedia?.("(pointer: coarse)")?.matches && !window.matchMedia?.("(any-pointer: fine)")?.matches)
@@ -338,7 +334,7 @@ export default function PromptInput(props: PromptInputProps) {
   createEffect(() => {
     // Scope global "type-to-focus" behavior to the active, visible prompt only.
     if (typeof document === "undefined") return
-    if (isCoarsePointer()) return
+    if (isTouchOnlyPointer()) return
     if (props.isActive === false) return
     if (props.disabled) return
 
@@ -374,6 +370,8 @@ export default function PromptInput(props: PromptInputProps) {
       const isSpecialKey =
         e.key === "Tab" ||
         e.key === "Enter" ||
+        e.key === " " ||
+        e.key === "Spacebar" ||
         e.key.startsWith("Arrow") ||
         e.key === "Backspace" ||
         e.key === "Delete"
@@ -385,6 +383,13 @@ export default function PromptInput(props: PromptInputProps) {
       // In session cache mode inactive panes are display:none; avoid stealing focus.
       if (textarea.offsetParent === null) return
 
+      if (e.key === "!" && prompt().length === 0) {
+        e.preventDefault()
+        setMode("shell")
+        textarea.focus()
+        return
+      }
+
       if (e.key.length === 1) {
         textarea.focus()
       }
@@ -510,6 +515,10 @@ export default function PromptInput(props: PromptInputProps) {
       void refreshHistory()
     }
 
+    if (!isTouchOnlyPointer()) {
+      focusConversationStream(wrapperRef?.closest(".session-view"))
+    }
+
     try {
       if (isShellMode) {
         if (props.onRunShell) {
@@ -536,10 +545,10 @@ export default function PromptInput(props: PromptInputProps) {
         detail: error instanceof Error ? error.message : String(error),
         variant: "error",
       })
-    } finally {
       if (!isTouchOnlyPointer()) {
         textareaRef?.focus()
       }
+      return
     }
   }
 
diff --git a/packages/ui/src/components/prompt-input/attachmentPlaceholders.ts b/packages/ui/src/components/prompt-input/attachmentPlaceholders.ts
index 1e009761..614a1400 100644
--- a/packages/ui/src/components/prompt-input/attachmentPlaceholders.ts
+++ b/packages/ui/src/components/prompt-input/attachmentPlaceholders.ts
@@ -1,3 +1,5 @@
+import { createAttachmentPlaceholderRegex } from "../../lib/attachment-placeholders"
+
 export function formatPastedPlaceholder(value: string | number) {
   return `[pasted #${value}]`
 }
@@ -7,11 +9,11 @@ export function formatImagePlaceholder(value: string | number) {
 }
 
 export function createPastedPlaceholderRegex() {
-  return /\[\s*pasted\s*#\s*(\d+)\s*\]/gi
+  return createAttachmentPlaceholderRegex("pasted")
 }
 
 export function createImagePlaceholderRegex() {
-  return /\[\s*Image\s*#\s*(\d+)\s*\]/gi
+  return createAttachmentPlaceholderRegex("image")
 }
 
 export function createMentionRegex() {
diff --git a/packages/ui/src/components/prompt-input/recording-controller.test.ts b/packages/ui/src/components/prompt-input/recording-controller.test.ts
new file mode 100644
index 00000000..11fa81c4
--- /dev/null
+++ b/packages/ui/src/components/prompt-input/recording-controller.test.ts
@@ -0,0 +1,275 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { createRecordingController } from "./recording-controller.ts"
+import type { RecordingControllerDeps, RecordingControllerCallbacks, StreamHandle } from "./recording-controller.ts"
+
+function createMockStream(): StreamHandle & { tracksStopped: boolean } {
+  return {
+    getTracks: () => [{ stop: () => {} }],
+    tracksStopped: false,
+  }
+}
+
+interface Harness {
+  deps: RecordingControllerDeps
+  callbacks: RecordingControllerCallbacks & {
+    states: string[]
+    transcripts: string[]
+    errors: { key: string; detail?: string }[]
+  }
+  recorder: { startCalled: boolean; stopCalled: boolean }
+}
+
+function createHarness(options?: {
+  getUserMedia?: RecordingControllerDeps["getUserMedia"]
+  setupRecorder?: RecordingControllerDeps["setupRecorder"]
+  transcribe?: RecordingControllerDeps["transcribe"]
+}): Harness {
+  const recorder = { startCalled: false, stopCalled: false }
+
+  const cbState = {
+    states: [] as string[],
+    transcripts: [] as string[],
+    errors: [] as { key: string; detail?: string }[],
+  }
+
+  const callbacks = {
+    ...cbState,
+    onStateChange: (s: string) => cbState.states.push(s),
+    onElapsedChange: () => {},
+    onTranscript: (text: string) => cbState.transcripts.push(text),
+    onError: (key: string, detail?: string) => cbState.errors.push({ key, detail }),
+  }
+
+  const deps: RecordingControllerDeps = {
+    isElectron: () => false,
+    requestMicAccess: async () => undefined,
+    getUserMedia: options?.getUserMedia ?? (async () => createMockStream()),
+    setupRecorder:
+      options?.setupRecorder ??
+      ((_stream, handlers) => ({
+        start: () => {
+          recorder.startCalled = true
+          handlers.onDataAvailable(new Blob(["audio"], { type: "audio/webm" }))
+        },
+        stop: () => {
+          recorder.stopCalled = true
+          queueMicrotask(() => handlers.onStop())
+        },
+        mimeType: "audio/webm;codecs=opus",
+      })),
+    stopTracks: (stream) => {
+      if (stream && "tracksStopped" in stream) {
+        ;(stream as unknown as { tracksStopped: boolean }).tracksStopped = true
+      }
+    },
+    blobToBase64: async () => "base64data",
+    transcribe: options?.transcribe ?? (async () => ({ text: "hello world" })),
+    setInterval: () => 0,
+    clearInterval: () => {},
+  }
+
+  return { deps, callbacks, recorder }
+}
+
+function flushPromises() {
+  return new Promise((resolve) => setTimeout(resolve, 0))
+}
+
+describe("recording controller", () => {
+  it("starts recording after getUserMedia resolves", async () => {
+    let resolveGum!: (s: StreamHandle) => void
+    const h = createHarness({
+      getUserMedia: () => new Promise((r) => { resolveGum = r }),
+    })
+
+    const c = createRecordingController(h.deps, h.callbacks)
+
+    const p = c.startRecording()
+    assert.equal(c.getState(), "idle")
+
+    resolveGum(createMockStream())
+    await p
+
+    assert.equal(c.getState(), "recording")
+    assert.equal(h.recorder.startCalled, true)
+    assert.deepEqual(h.callbacks.states, ["recording"])
+  })
+
+  it("cancels pending acquisition when stopped before getUserMedia resolves", async () => {
+    let resolveGum!: (s: StreamHandle) => void
+    const h = createHarness({
+      getUserMedia: () => new Promise((r) => { resolveGum = r }),
+    })
+
+    const c = createRecordingController(h.deps, h.callbacks)
+
+    const p = c.startRecording()
+    c.stopRecording()
+    resolveGum(createMockStream())
+    await p
+    await flushPromises()
+
+    assert.equal(c.getState(), "idle")
+    assert.equal(h.recorder.startCalled, false)
+  })
+
+  it("stops the returned stream when cancelled before resolution", async () => {
+    let resolveGum!: (s: StreamHandle) => void
+    const h = createHarness({
+      getUserMedia: () => new Promise((r) => { resolveGum = r }),
+    })
+
+    const c = createRecordingController(h.deps, h.callbacks)
+    const p = c.startRecording()
+    c.stopRecording()
+
+    const stream = createMockStream()
+    resolveGum(stream)
+    await p
+    await flushPromises()
+
+    assert.equal(stream.tracksStopped, true)
+  })
+
+  it("transcribes and reports transcript on normal stop", async () => {
+    const h = createHarness()
+    const c = createRecordingController(h.deps, h.callbacks)
+
+    await c.startRecording()
+    assert.equal(c.getState(), "recording")
+
+    c.stopRecording()
+    await flushPromises()
+
+    assert.deepEqual(h.callbacks.transcripts, ["hello world"])
+    assert.equal(c.getState(), "idle")
+  })
+
+  it("does not transcribe when no audio chunks collected", async () => {
+    const h = createHarness({
+      setupRecorder: (_stream, handlers) => ({
+        start: () => {},
+        stop: () => { queueMicrotask(() => handlers.onStop()) },
+        mimeType: "audio/webm",
+      }),
+    })
+    const c = createRecordingController(h.deps, h.callbacks)
+
+    await c.startRecording()
+    c.stopRecording()
+    await flushPromises()
+
+    assert.deepEqual(h.callbacks.transcripts, [])
+    assert.equal(c.getState(), "idle")
+  })
+
+  it("allows next recording after cancelled start", async () => {
+    let resolveGum1!: (s: StreamHandle) => void
+    let firstCall = true
+    const h = createHarness({
+      getUserMedia: () => {
+        if (firstCall) {
+          firstCall = false
+          return new Promise((r) => { resolveGum1 = r })
+        }
+        return Promise.resolve(createMockStream())
+      },
+    })
+
+    const c = createRecordingController(h.deps, h.callbacks)
+    const p = c.startRecording()
+    c.stopRecording()
+
+    resolveGum1(createMockStream())
+    await p
+    await flushPromises()
+
+    assert.equal(c.getState(), "idle")
+    assert.equal(h.recorder.startCalled, false)
+
+    await c.startRecording()
+    assert.equal(c.getState(), "recording")
+    assert.equal(h.recorder.startCalled, true)
+  })
+
+  it("prevents start while transcribing", async () => {
+    let resolveTranscribe!: () => void
+    const h = createHarness({
+      transcribe: () => new Promise((r) => { resolveTranscribe = () => r({ text: "hello" }) }),
+    })
+
+    const c = createRecordingController(h.deps, h.callbacks)
+
+    await c.startRecording()
+    c.stopRecording()
+    await flushPromises()
+
+    assert.equal(c.getState(), "transcribing")
+
+    await c.startRecording()
+    assert.equal(c.getState(), "transcribing")
+
+    resolveTranscribe()
+    await flushPromises()
+    assert.equal(c.getState(), "idle")
+  })
+
+  it("reports error when transcribe fails", async () => {
+    const h = createHarness({
+      transcribe: async () => { throw new Error("server error") },
+    })
+
+    const c = createRecordingController(h.deps, h.callbacks)
+
+    await c.startRecording()
+    c.stopRecording()
+    await flushPromises()
+
+    assert.equal(h.callbacks.errors.length, 1)
+    assert.equal(h.callbacks.errors[0].key, "promptInput.voiceInput.error.transcribe")
+    assert.equal(h.callbacks.errors[0].detail, "server error")
+    assert.equal(c.getState(), "idle")
+  })
+
+  it("increments generation on cleanup, invalidating pending requests", async () => {
+    let resolveGum!: (s: StreamHandle) => void
+    const h = createHarness({
+      getUserMedia: () => new Promise((r) => { resolveGum = r }),
+    })
+
+    const c = createRecordingController(h.deps, h.callbacks)
+
+    const p = c.startRecording()
+    c.cleanup(false)
+    resolveGum(createMockStream())
+    await p
+    await flushPromises()
+
+    assert.equal(h.recorder.startCalled, false)
+    assert.equal(c.getState(), "idle")
+  })
+
+  it("skips transcript for stale generation after cleanup during transcription", async () => {
+    let resolveTranscribe!: () => void
+    const h = createHarness({
+      transcribe: () => new Promise((r) => { resolveTranscribe = () => r({ text: "stale" }) }),
+    })
+
+    const c = createRecordingController(h.deps, h.callbacks)
+
+    await c.startRecording()
+    c.stopRecording()
+    await flushPromises()
+
+    assert.equal(c.getState(), "transcribing")
+
+    c.cleanup(true)
+    resolveTranscribe()
+    await flushPromises()
+
+    assert.deepEqual(h.callbacks.transcripts, [])
+    assert.equal(c.getState(), "idle")
+  })
+})
diff --git a/packages/ui/src/components/prompt-input/recording-controller.ts b/packages/ui/src/components/prompt-input/recording-controller.ts
new file mode 100644
index 00000000..3af34fc7
--- /dev/null
+++ b/packages/ui/src/components/prompt-input/recording-controller.ts
@@ -0,0 +1,209 @@
+export type RecordingState = "idle" | "recording" | "transcribing"
+
+export interface StreamHandle {
+  getTracks(): { stop(): void }[]
+}
+
+export interface RecorderHandle {
+  start(): void
+  stop(): void
+  readonly mimeType: string
+}
+
+export interface RecordingControllerDeps {
+  isElectron: () => boolean
+  requestMicAccess: () => Promise<{ granted: boolean } | undefined>
+  getUserMedia: () => Promise<StreamHandle>
+  setupRecorder: (
+    stream: StreamHandle,
+    handlers: {
+      onDataAvailable: (chunk: Blob) => void
+      onStop: () => void
+    },
+  ) => RecorderHandle
+  stopTracks: (stream: StreamHandle | null) => void
+  blobToBase64: (blob: Blob) => Promise<string>
+  transcribe: (input: { audioBase64: string; mimeType: string }) => Promise<{ text: string }>
+  setInterval: (fn: () => void, ms: number) => number
+  clearInterval: (id: number | undefined) => void
+}
+
+export interface RecordingControllerCallbacks {
+  onStateChange: (state: RecordingState) => void
+  onElapsedChange: (ms: number) => void
+  onTranscript: (text: string) => void
+  onError: (errorKey: string, detail?: string) => void
+}
+
+export function createRecordingController(
+  deps: RecordingControllerDeps,
+  callbacks: RecordingControllerCallbacks,
+) {
+  let state: RecordingState = "idle"
+  let recorder: RecorderHandle | null = null
+  let mediaStream: StreamHandle | null = null
+  let timerId: number | undefined
+  let recordedChunks: Blob[] = []
+  let recordingStartedAt = 0
+  let requestGeneration = 0
+
+  function setState(next: RecordingState) {
+    state = next
+    callbacks.onStateChange(next)
+  }
+
+  function setElapsed(next: number) {
+    callbacks.onElapsedChange(next)
+  }
+
+  function getState() {
+    return state
+  }
+
+  function stopRecording() {
+    if (state === "idle") {
+      requestGeneration += 1
+      return
+    }
+    if (state !== "recording" || !recorder) return
+    recorder.stop()
+    setState("transcribing")
+    stopTimer()
+  }
+
+  async function startRecording() {
+    if (state === "transcribing" || state === "recording") return
+
+    const generation = ++requestGeneration
+
+    try {
+      recordedChunks = []
+
+      if (deps.isElectron()) {
+        const granted = await deps.requestMicAccess()
+        if (generation !== requestGeneration) return
+        if (granted && !granted.granted) {
+          callbacks.onError("promptInput.voiceInput.error.permissionDenied")
+          return
+        }
+      }
+
+      const stream = await deps.getUserMedia()
+
+      if (generation !== requestGeneration) {
+        deps.stopTracks(stream)
+        return
+      }
+
+      mediaStream = stream
+      const rec = deps.setupRecorder(stream, {
+        onDataAvailable: (chunk) => {
+          if (generation !== requestGeneration) return
+          if (chunk.size > 0) {
+            recordedChunks.push(chunk)
+          }
+        },
+        onStop: () => {
+          if (generation === requestGeneration) {
+            void finalizeRecording(generation)
+          }
+        },
+      })
+      recorder = rec
+
+      recordingStartedAt = Date.now()
+      setElapsed(0)
+      setState("recording")
+      startTimer()
+      rec.start()
+    } catch (error) {
+      if (generation !== requestGeneration) return
+      cleanupMedia(false)
+      callbacks.onError(
+        "promptInput.voiceInput.error.permission",
+        error instanceof Error ? error.message : String(error),
+      )
+    }
+  }
+
+  async function finalizeRecording(generation: number) {
+    const rec = recorder
+    const stream = mediaStream
+    recorder = null
+    mediaStream = null
+
+    if (recordedChunks.length === 0) {
+      recordedChunks = []
+      deps.stopTracks(stream)
+      setState("idle")
+      setElapsed(0)
+      return
+    }
+
+    const mimeType = rec?.mimeType || recordedChunks[0]?.type || "audio/webm"
+
+    const audioBlob = new Blob(recordedChunks, { type: mimeType })
+    recordedChunks = []
+    deps.stopTracks(stream)
+
+    try {
+      const transcription = await deps.transcribe({
+        audioBase64: await deps.blobToBase64(audioBlob),
+        mimeType,
+      })
+      const text = transcription.text.trim()
+      if (generation === requestGeneration && text) {
+        callbacks.onTranscript(text)
+      }
+    } catch (error) {
+      if (generation === requestGeneration) {
+        callbacks.onError(
+          "promptInput.voiceInput.error.transcribe",
+          error instanceof Error ? error.message : String(error),
+        )
+      }
+    } finally {
+      if (generation === requestGeneration) {
+        setState("idle")
+        setElapsed(0)
+      }
+    }
+  }
+
+  function cleanupMedia(resetState = true) {
+    requestGeneration += 1
+    stopTimer()
+    if (recorder) {
+      recorder.stop()
+    }
+    recorder = null
+    deps.stopTracks(mediaStream)
+    mediaStream = null
+    recordedChunks = []
+    if (resetState) {
+      setState("idle")
+      setElapsed(0)
+    }
+  }
+
+  function startTimer() {
+    stopTimer()
+    timerId = deps.setInterval(() => {
+      setElapsed(Date.now() - recordingStartedAt)
+    }, 250)
+  }
+
+  function stopTimer() {
+    if (timerId !== undefined) {
+      deps.clearInterval(timerId)
+      timerId = undefined
+    }
+  }
+
+  return {
+    getState,
+    startRecording,
+    stopRecording,
+    cleanup: cleanupMedia,
+  }
+}
diff --git a/packages/ui/src/components/prompt-input/usePromptAttachments.ts b/packages/ui/src/components/prompt-input/usePromptAttachments.ts
index 99512199..c3fd0a5a 100644
--- a/packages/ui/src/components/prompt-input/usePromptAttachments.ts
+++ b/packages/ui/src/components/prompt-input/usePromptAttachments.ts
@@ -2,6 +2,8 @@ import { createEffect, createSignal, type Accessor } from "solid-js"
 import { addAttachment, getAttachments, removeAttachment } from "../../stores/attachments"
 import { createFileAttachment, createTextAttachment } from "../../types/attachment"
 import type { Attachment } from "../../types/attachment"
+import { createAttachmentPlaceholderRegex } from "../../lib/attachment-placeholders"
+import { createPromptMentionRegex, getAttachmentPromptMentionCandidates } from "../../lib/attachment-mentions"
 import { tGlobal } from "../../lib/i18n"
 import { getFilePath } from "../../lib/native/file-path"
 import { showToastNotification } from "../../lib/notifications"
@@ -55,8 +57,6 @@ export function usePromptAttachments(options: PromptAttachmentsOptions): PromptA
     setImageCount(highestImage)
   }
 
-  const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
-
   function removeTokenFromPrompt(currentPrompt: string, tokenRegex: RegExp) {
     const next = currentPrompt.replace(tokenRegex, "")
     if (next === currentPrompt) return currentPrompt
@@ -68,11 +68,6 @@ export function usePromptAttachments(options: PromptAttachmentsOptions): PromptA
       .trim()
   }
 
-  const createLooseImagePlaceholderRegex = (counter: string | number) =>
-    new RegExp(`\\[\\s*Image\\s*#\\s*${counter}\\s*\\]`, "i")
-  const createLoosePastedPlaceholderRegex = (counter: string | number) =>
-    new RegExp(`\\[\\s*pasted\\s*#\\s*${counter}\\s*\\]`, "i")
-
   // Keep placeholder-backed attachments in sync with prompt text.
   // If the placeholder token disappears from the prompt, the attachment should disappear too.
   createEffect(() => {
@@ -86,7 +81,7 @@ export function usePromptAttachments(options: PromptAttachmentsOptions): PromptA
         const match = attachment.display.match(pastedDisplayCounterRegex)
         if (!match) continue
         const counter = match[1]
-        if (!createLoosePastedPlaceholderRegex(counter).test(currentPrompt)) {
+        if (!createAttachmentPlaceholderRegex("pasted", counter, { global: false }).test(currentPrompt)) {
           toRemove.push(attachment.id)
         }
         continue
@@ -97,7 +92,7 @@ export function usePromptAttachments(options: PromptAttachmentsOptions): PromptA
           attachment.display.match(bracketedImageDisplayCounterRegex) || attachment.display.match(imageDisplayCounterRegex)
         if (!match) continue
         const counter = match[1]
-        if (!createLooseImagePlaceholderRegex(counter).test(currentPrompt)) {
+        if (!createAttachmentPlaceholderRegex("image", counter, { global: false }).test(currentPrompt)) {
           toRemove.push(attachment.id)
         }
       }
@@ -120,30 +115,33 @@ export function usePromptAttachments(options: PromptAttachmentsOptions): PromptA
     const currentPrompt = options.prompt()
     let nextPrompt = currentPrompt
 
+    let hasPlaceholder = false
     if (attachment.source.type === "file") {
       if (attachment.mediaType.startsWith("image/")) {
         const imageMatch =
           attachment.display.match(bracketedImageDisplayCounterRegex) || attachment.display.match(imageDisplayCounterRegex)
         if (imageMatch) {
-          nextPrompt = removeTokenFromPrompt(currentPrompt, createLooseImagePlaceholderRegex(imageMatch[1]))
-        }
-      } else {
-        // For file mentions we insert `@<path>`, but the chip might display `@<filename>`.
-        const candidates = [attachment.source.path, attachment.filename]
-        for (const candidate of candidates) {
-          if (!candidate) continue
-          const mentionRegex = new RegExp(`@${escapeRegExp(candidate)}(?=\\s|$)`, "i")
-          nextPrompt = removeTokenFromPrompt(nextPrompt, mentionRegex)
+          hasPlaceholder = true
+          nextPrompt = removeTokenFromPrompt(
+            currentPrompt,
+            createAttachmentPlaceholderRegex("image", imageMatch[1], { global: false }),
+          )
         }
       }
-    } else if (attachment.source.type === "agent") {
-      const agentName = attachment.filename
-      const mentionRegex = new RegExp(`@${escapeRegExp(agentName)}(?=\\s|$)`, "i")
-      nextPrompt = removeTokenFromPrompt(currentPrompt, mentionRegex)
     } else if (attachment.source.type === "text") {
       const placeholderMatch = attachment.display.match(pastedDisplayCounterRegex)
       if (placeholderMatch) {
-        nextPrompt = removeTokenFromPrompt(currentPrompt, createLoosePastedPlaceholderRegex(placeholderMatch[1]))
+        hasPlaceholder = true
+        nextPrompt = removeTokenFromPrompt(
+          currentPrompt,
+          createAttachmentPlaceholderRegex("pasted", placeholderMatch[1], { global: false }),
+        )
+      }
+    }
+
+    if (!hasPlaceholder) {
+      for (const candidate of getAttachmentPromptMentionCandidates(attachment)) {
+        nextPrompt = removeTokenFromPrompt(nextPrompt, createPromptMentionRegex(candidate))
       }
     }
 
diff --git a/packages/ui/src/components/prompt-input/usePromptState.ts b/packages/ui/src/components/prompt-input/usePromptState.ts
index 3b326f2c..2c11d8b0 100644
--- a/packages/ui/src/components/prompt-input/usePromptState.ts
+++ b/packages/ui/src/components/prompt-input/usePromptState.ts
@@ -1,6 +1,11 @@
 import { createEffect, createSignal, on, onCleanup, onMount, type Accessor } from "solid-js"
 import { addToHistory, getHistory } from "../../stores/message-history"
-import { clearSessionDraftPrompt, getSessionDraftPrompt, setSessionDraftPrompt } from "../../stores/sessions"
+import {
+  clearSessionDraftPrompt,
+  getSessionDraftPrompt,
+  onSessionDraftHydrated,
+  setSessionDraftPrompt,
+} from "../../stores/sessions"
 import { getLogger } from "../../lib/logger"
 
 const log = getLogger("actions")
@@ -71,6 +76,18 @@ export function usePromptState(options: PromptStateOptions): PromptState {
     setHistoryDraft(null)
   }
 
+  const stopListeningForDraftHydration = onSessionDraftHydrated((instanceId, sessionId, draft) => {
+    if (instanceId !== options.instanceId() || sessionId !== options.sessionId()) return
+    if (historyIndex() !== -1) {
+      setHistoryDraft(draft)
+      return
+    }
+    setPromptInternal(draft)
+    setDraftLoadedNonce((prev) => prev + 1)
+    options.onSessionDraftLoaded?.(draft)
+  })
+  onCleanup(stopListeningForDraftHydration)
+
   createEffect(
     on(
       () => `${options.instanceId()}:${options.sessionId()}`,
@@ -80,13 +97,14 @@ export function usePromptState(options: PromptStateOptions): PromptState {
 
         onCleanup(() => {
           // Persist the previous session's draft when switching sessions.
-          setSessionDraftPrompt(instanceId, sessionId, prompt())
+          if (prompt() !== getSessionDraftPrompt(instanceId, sessionId)) {
+            setSessionDraftPrompt(instanceId, sessionId, prompt())
+          }
         })
 
         const storedPrompt = getSessionDraftPrompt(instanceId, sessionId)
 
         setPromptInternal(storedPrompt)
-        setSessionDraftPrompt(instanceId, sessionId, storedPrompt)
 
         resetHistoryNavigation()
 
diff --git a/packages/ui/src/components/prompt-input/usePromptVoiceInput.ts b/packages/ui/src/components/prompt-input/usePromptVoiceInput.ts
index 0ff87d07..4b78984b 100644
--- a/packages/ui/src/components/prompt-input/usePromptVoiceInput.ts
+++ b/packages/ui/src/components/prompt-input/usePromptVoiceInput.ts
@@ -4,6 +4,8 @@ import { loadSpeechCapabilities, speechCapabilities } from "../../stores/speech"
 import { serverApi } from "../../lib/api-client"
 import { useI18n } from "../../lib/i18n"
 import { isElectronHost } from "../../lib/runtime-env"
+import { blobToBase64, createMediaRecorder, stopTracks } from "../../lib/audio-utils"
+import { createRecordingController, type RecordingState } from "./recording-controller"
 
 interface UsePromptVoiceInputOptions {
   prompt: Accessor<string>
@@ -13,26 +15,65 @@ interface UsePromptVoiceInputOptions {
   disabled: Accessor<boolean>
 }
 
-type VoiceInputState = "idle" | "recording" | "transcribing"
-
 export function usePromptVoiceInput(options: UsePromptVoiceInputOptions) {
   const { t } = useI18n()
-  const [state, setState] = createSignal<VoiceInputState>("idle")
+  const [state, setState] = createSignal<RecordingState>("idle")
   const [elapsedMs, setElapsedMs] = createSignal(0)
 
-  let mediaRecorder: MediaRecorder | null = null
-  let mediaStream: MediaStream | null = null
-  let timerId: number | undefined
-  let shouldTranscribe = true
-  let recordedChunks: Blob[] = []
-  let recordingStartedAt = 0
+  const controller = createRecordingController(
+    {
+      isElectron: () => isElectronHost(),
+      requestMicAccess: async () =>
+        (window as Window & { electronAPI?: ElectronAPI }).electronAPI?.requestMicrophoneAccess?.(),
+      getUserMedia: async () => navigator.mediaDevices.getUserMedia({ audio: true }),
+      setupRecorder: (stream, handlers) => {
+        const recorder = createMediaRecorder(stream as MediaStream)
+        let stopped = false
+        recorder.addEventListener("dataavailable", (event) => {
+          if (event.data.size > 0) handlers.onDataAvailable(event.data)
+        })
+        recorder.addEventListener("stop", () => handlers.onStop())
+        return {
+          start: () => recorder.start(),
+          stop: () => {
+            if (!stopped) {
+              stopped = true
+              if (recorder.state === "recording") {
+                recorder.stop()
+              }
+            }
+          },
+          mimeType: recorder.mimeType,
+        }
+      },
+      stopTracks: (stream) => stopTracks(stream as MediaStream | null),
+      blobToBase64,
+      transcribe: (input) => serverApi.transcribeAudio(input),
+      setInterval: (fn, ms) => window.setInterval(fn, ms),
+      clearInterval: (id) => {
+        if (id !== undefined) window.clearInterval(id)
+      },
+    },
+    {
+      onStateChange: setState,
+      onElapsedChange: setElapsedMs,
+      onTranscript: (text) => insertTranscript(text),
+      onError: (errorKey, detail) => {
+        showAlertDialog(t(errorKey), {
+          title: t("promptInput.voiceInput.error.title"),
+          ...(detail ? { detail } : {}),
+          variant: "error",
+        })
+      },
+    },
+  )
 
   createEffect(() => {
     void loadSpeechCapabilities()
   })
 
   onCleanup(() => {
-    cleanupMedia(false)
+    controller.cleanup(false)
   })
 
   const isSupported = () => {
@@ -46,35 +87,11 @@ export function usePromptVoiceInput(options: UsePromptVoiceInputOptions) {
       options.enabled() &&
         isSupported() &&
         capabilities?.available &&
-        capabilities?.configured &&
+        capabilities?.sttConfigured &&
         capabilities?.supportsStt,
     )
   }
 
-  async function toggleRecording(): Promise<void> {
-    if (state() === "recording") {
-      stopRecording()
-      return
-    }
-
-    await startRecording()
-  }
-
-  function stopRecording() {
-    if (!mediaRecorder || state() !== "recording") return
-    shouldTranscribe = true
-    mediaRecorder.stop()
-    setState("transcribing")
-    stopTimer()
-  }
-
-  function cancelRecording() {
-    if (!mediaRecorder || state() !== "recording") return
-    shouldTranscribe = false
-    mediaRecorder.stop()
-    cleanupMedia(false)
-  }
-
   async function startRecording() {
     if (!canUseVoiceInput() || options.disabled() || state() === "transcribing" || state() === "recording") return
 
@@ -86,82 +103,20 @@ export function usePromptVoiceInput(options: UsePromptVoiceInputOptions) {
       return
     }
 
-    try {
-      recordedChunks = []
-      shouldTranscribe = true
-
-      if (isElectronHost()) {
-        const granted = await (window as Window & { electronAPI?: ElectronAPI }).electronAPI?.requestMicrophoneAccess?.()
-        if (granted && !granted.granted) {
-          throw new Error(t("promptInput.voiceInput.error.permissionDenied"))
-        }
-      }
-
-      mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true })
-      mediaRecorder = createRecorder(mediaStream)
-
-      mediaRecorder.addEventListener("dataavailable", (event) => {
-        if (event.data.size > 0) {
-          recordedChunks.push(event.data)
-        }
-      })
-
-      mediaRecorder.addEventListener("stop", () => {
-        void finalizeRecording()
-      })
-
-      recordingStartedAt = Date.now()
-      setElapsedMs(0)
-      setState("recording")
-      startTimer()
-      mediaRecorder.start()
-    } catch (error) {
-      cleanupMedia(false)
-      showAlertDialog(t("promptInput.voiceInput.error.permission"), {
-        title: t("promptInput.voiceInput.error.title"),
-        detail: error instanceof Error ? error.message : String(error),
-        variant: "error",
-      })
-    }
+    await controller.startRecording()
   }
 
-  async function finalizeRecording() {
-    const recorder = mediaRecorder
-    const stream = mediaStream
-    mediaRecorder = null
-    mediaStream = null
+  function stopRecording() {
+    controller.stopRecording()
+  }
 
-    if (!shouldTranscribe || recordedChunks.length === 0) {
-      recordedChunks = []
-      stopTracks(stream)
-      setState("idle")
-      setElapsedMs(0)
+  async function toggleRecording(): Promise<void> {
+    if (state() === "recording") {
+      stopRecording()
       return
     }
 
-    const mimeType = recorder?.mimeType || recordedChunks[0]?.type || "audio/webm"
-
-    try {
-      const audioBlob = new Blob(recordedChunks, { type: mimeType })
-      const transcription = await serverApi.transcribeAudio({
-        audioBase64: await blobToBase64(audioBlob),
-        mimeType,
-      })
-      if (transcription.text.trim()) {
-        insertTranscript(transcription.text.trim())
-      }
-    } catch (error) {
-      showAlertDialog(t("promptInput.voiceInput.error.transcribe"), {
-        title: t("promptInput.voiceInput.error.title"),
-        detail: error instanceof Error ? error.message : String(error),
-        variant: "error",
-      })
-    } finally {
-      recordedChunks = []
-      stopTracks(stream)
-      setState("idle")
-      setElapsedMs(0)
-    }
+    await startRecording()
   }
 
   function insertTranscript(text: string) {
@@ -192,35 +147,6 @@ export function usePromptVoiceInput(options: UsePromptVoiceInputOptions) {
     }
   }
 
-  function cleanupMedia(resetState = true) {
-    stopTimer()
-    if (mediaRecorder && mediaRecorder.state !== "inactive") {
-      mediaRecorder.stop()
-    }
-    mediaRecorder = null
-    stopTracks(mediaStream)
-    mediaStream = null
-    recordedChunks = []
-    if (resetState) {
-      setState("idle")
-      setElapsedMs(0)
-    }
-  }
-
-  function startTimer() {
-    stopTimer()
-    timerId = window.setInterval(() => {
-      setElapsedMs(Date.now() - recordingStartedAt)
-    }, 250)
-  }
-
-  function stopTimer() {
-    if (timerId !== undefined) {
-      window.clearInterval(timerId)
-      timerId = undefined
-    }
-  }
-
   return {
     state,
     elapsedMs,
@@ -228,7 +154,6 @@ export function usePromptVoiceInput(options: UsePromptVoiceInputOptions) {
     startRecording,
     stopRecording,
     toggleRecording,
-    cancelRecording,
     isRecording: () => state() === "recording",
     isTranscribing: () => state() === "transcribing",
     buttonTitle: () => {
@@ -238,23 +163,3 @@ export function usePromptVoiceInput(options: UsePromptVoiceInputOptions) {
     },
   }
 }
-
-function createRecorder(stream: MediaStream): MediaRecorder {
-  const candidates = ["audio/webm;codecs=opus", "audio/webm", "audio/mp4", "audio/ogg;codecs=opus"]
-  const supported = candidates.find((candidate) => typeof MediaRecorder.isTypeSupported !== "function" || MediaRecorder.isTypeSupported(candidate))
-  return supported ? new MediaRecorder(stream, { mimeType: supported }) : new MediaRecorder(stream)
-}
-
-function stopTracks(stream: MediaStream | null) {
-  stream?.getTracks().forEach((track) => track.stop())
-}
-
-async function blobToBase64(blob: Blob): Promise<string> {
-  const buffer = await blob.arrayBuffer()
-  const bytes = new Uint8Array(buffer)
-  let binary = ""
-  for (const byte of bytes) {
-    binary += String.fromCharCode(byte)
-  }
-  return btoa(binary)
-}
diff --git a/packages/ui/src/components/provider-auth/provider-manager-modal.tsx b/packages/ui/src/components/provider-auth/provider-manager-modal.tsx
index 89cbf3b6..a7f4e5b8 100644
--- a/packages/ui/src/components/provider-auth/provider-manager-modal.tsx
+++ b/packages/ui/src/components/provider-auth/provider-manager-modal.tsx
@@ -1,6 +1,6 @@
 import { Dialog } from "@kobalte/core/dialog"
 import { Select } from "@kobalte/core/select"
-import { createEffect, createMemo, createSignal, For, Show, type Component } from "solid-js"
+import { createEffect, createMemo, createSignal, For, onCleanup, Show, type Component } from "solid-js"
 import { Check, ChevronDown, ExternalLink, KeyRound, Loader2, PlugZap, RefreshCw, ShieldCheck, X } from "lucide-solid"
 import type { OpencodeClient } from "@opencode-ai/sdk/v2/client"
 import { openExternalUrl } from "../../lib/external-url"
@@ -45,8 +45,9 @@ type DisconnectMode = "auth-remove" | "disable-in-config" | "not-disconnectable"
 
 interface ProviderManagerModalProps {
   instanceId: string
-  open: boolean
-  onOpenChange: (open: boolean) => void
+  open?: boolean
+  embedded?: boolean
+  onOpenChange?: (open: boolean) => void
 }
 
 function modelCountFromProvider(provider: any): number {
@@ -78,9 +79,15 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
   const [authorizationLinkCopied, setAuthorizationLinkCopied] = createSignal(false)
   let callbackAbortController: AbortController | null = null
   let pendingOauthPopup: Window | null = null
+  let loadVersion = 0
+  let authOperationVersion = 0
+  let oauthCodeInput: HTMLInputElement | undefined
 
   const instance = createMemo(() => instances().get(props.instanceId) ?? null)
-  const client = createMemo<OpencodeClient | null>(() => instance()?.client ?? null)
+  const client = createMemo<OpencodeClient | null>(() => {
+    const current = instance()
+    return current?.status === "ready" ? current.client ?? null : null
+  })
 
   const providerNameById = createMemo(() => {
     const names = new Map<string, string>()
@@ -175,7 +182,7 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
 
   function handleModalOpenChange(open: boolean) {
     if (!open) resetFlow(null)
-    props.onOpenChange(open)
+    props.onOpenChange?.(open)
   }
 
   function isBrowserHostForOAuth(): boolean {
@@ -234,13 +241,24 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
   }
 
   createEffect(() => {
-    if (!props.open) return
+    const version = ++loadVersion
+    resetProviderData()
+    if (!props.embedded && !props.open) return
     const authClient = client()
     if (!authClient) return
-    void loadProviderData(authClient)
+    void loadProviderData(authClient, version)
   })
 
-  async function loadProviderData(authClient: OpencodeClient): Promise<void> {
+  createEffect(() => {
+    if (stage() === "code") queueMicrotask(() => oauthCodeInput?.focus())
+  })
+
+  onCleanup(() => {
+    loadVersion += 1
+    disposePendingAuth()
+  })
+
+  async function loadProviderData(authClient: OpencodeClient, version = ++loadVersion): Promise<void> {
     setLoading(true)
     setLoadError(null)
     try {
@@ -249,6 +267,7 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
         (authClient as any).provider.auth(),
         (authClient as any).config.get(),
       ])
+      if (version !== loadVersion) return
       const nextConfigData = (configResponse?.data ?? {}) as Record<string, any>
       const nextConfiguredIds = new Set(Object.keys((nextConfigData.provider ?? {}) as Record<string, unknown>))
       const listed = ((providerListResponse?.data?.all ?? []) as any[]).map((provider) => ({
@@ -267,19 +286,35 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
       setMethodsByProvider((authResponse?.data ?? {}) as Record<string, ProviderAuthMethod[]>)
       setSelectedProviderId((current) => current ?? listed[0]?.id ?? Object.keys(authResponse?.data ?? {})[0] ?? null)
     } catch (error) {
+      if (version !== loadVersion) return
       setLoadError(extractProviderAuthErrorMessage(error, t("settings.providers.errors.loadFailed")))
     } finally {
-      setLoading(false)
+      if (version === loadVersion) setLoading(false)
     }
   }
 
-  function resetFlow(nextProviderId: string | null = null) {
+  function disposePendingAuth() {
+    authOperationVersion += 1
     callbackAbortController?.abort()
     callbackAbortController = null
-    if (pendingOauthPopup && !pendingOauthPopup.closed) {
-      pendingOauthPopup.close()
-    }
+    if (pendingOauthPopup && !pendingOauthPopup.closed) pendingOauthPopup.close()
     pendingOauthPopup = null
+  }
+
+  function resetProviderData() {
+    resetFlow(null)
+    setMethodsByProvider({})
+    setAvailableProviders([])
+    setConnectedProviderIds(new Set<string>())
+    setConfiguredProviderIds(new Set<string>())
+    setConfigData({})
+    setSelectedProviderId(null)
+    setLoadError(null)
+    setLoading(false)
+  }
+
+  function resetFlow(nextProviderId: string | null = null) {
+    disposePendingAuth()
     setActiveProviderId(nextProviderId)
     setSelectedMethodIndex(0)
     setApiKey("")
@@ -296,30 +331,40 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
     setPromptValues((current) => ({ ...current, [key]: value }))
   }
 
-  async function refreshAfterAuth(authClient: OpencodeClient) {
+  function isCurrentOperation(version: number, instanceId: string, authClient: OpencodeClient) {
+    return version === authOperationVersion && props.instanceId === instanceId && client() === authClient
+  }
+
+  async function refreshAfterAuth(authClient: OpencodeClient, instanceId: string, operationVersion: number) {
+    if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
     await (authClient as any).global.dispose().catch(() => undefined)
-    await fetchProviders(props.instanceId).catch(() => undefined)
+    if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
+    await fetchProviders(instanceId).catch(() => undefined)
+    if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
     await loadProviderData(authClient).catch(() => undefined)
   }
 
-  async function submitApiAuth(providerId: string, authClient: OpencodeClient) {
+  async function submitApiAuth(providerId: string, authClient: OpencodeClient, instanceId: string, operationVersion: number) {
     await requestData(
       (authClient as any).auth.set({ providerID: providerId, auth: { type: "api", key: apiKey().trim() } }),
       "auth.set",
     )
-    await refreshAfterAuth(authClient)
-    resetFlow(null)
+    if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
+    await refreshAfterAuth(authClient, instanceId, operationVersion)
+    if (isCurrentOperation(operationVersion, instanceId, authClient)) resetFlow(null)
   }
 
-  async function submitOAuthAuthorize(providerId: string, authClient: OpencodeClient) {
+  async function submitOAuthAuthorize(providerId: string, authClient: OpencodeClient, instanceId: string, operationVersion: number) {
     const response = await (authClient as any).provider.oauth.authorize(
       { providerID: providerId, method: selectedMethodIndex() },
       { throwOnError: true },
     )
+    if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
     const data = response?.data as ProviderAuthAuthorization | undefined
     if (!data) throw new Error(t("settings.providers.errors.noAuthorization"))
     setAuthorization(data)
     const opened = await launchAuthorizationUrl(data.url, { popup: pendingOauthPopup })
+    if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
     pendingOauthPopup = null
     setAuthorizationLaunchBlocked(!opened)
     if (data.method === "code") {
@@ -335,26 +380,30 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
       ),
       "provider.oauth.callback",
     )
+    if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
     callbackAbortController = null
-    await refreshAfterAuth(authClient)
-    resetFlow(null)
+    await refreshAfterAuth(authClient, instanceId, operationVersion)
+    if (isCurrentOperation(operationVersion, instanceId, authClient)) resetFlow(null)
   }
 
   async function submitAuth() {
     const providerId = activeProviderId()
     const authClient = client()
     if (!providerId || !authClient || !canSubmit()) return
+    const instanceId = props.instanceId
+    const operationVersion = ++authOperationVersion
     setStage("authorizing")
     setActionError(null)
     try {
       if (selectedMethod().type === "api") {
-        await submitApiAuth(providerId, authClient)
+        await submitApiAuth(providerId, authClient, instanceId, operationVersion)
         return
       }
       pendingOauthPopup = prepareOAuthPopupWindow()
       setAuthorizationLaunchBlocked(isBrowserHostForOAuth() && pendingOauthPopup === null)
-      await submitOAuthAuthorize(providerId, authClient)
+      await submitOAuthAuthorize(providerId, authClient, instanceId, operationVersion)
     } catch (error) {
+      if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
       if (pendingOauthPopup && !pendingOauthPopup.closed) {
         pendingOauthPopup.close()
       }
@@ -372,6 +421,8 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
     const providerId = activeProviderId()
     const authClient = client()
     if (!providerId || !authClient || !code().trim()) return
+    const instanceId = props.instanceId
+    const operationVersion = ++authOperationVersion
     setStage("authorizing")
     setActionError(null)
     try {
@@ -379,9 +430,11 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
         (authClient as any).provider.oauth.callback({ providerID: providerId, method: selectedMethodIndex(), code: code().trim() }),
         "provider.oauth.callback",
       )
-      await refreshAfterAuth(authClient)
-      resetFlow(null)
+      if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
+      await refreshAfterAuth(authClient, instanceId, operationVersion)
+      if (isCurrentOperation(operationVersion, instanceId, authClient)) resetFlow(null)
     } catch (error) {
+      if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
       setActionError(extractProviderAuthErrorMessage(error, t("settings.providers.errors.authorizationFailed")))
       setStage("code")
     }
@@ -391,6 +444,9 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
     const authClient = client()
     const provider = availableProviders().find((item) => item.id === providerId)
     if (!authClient || !provider) return
+    const instanceId = props.instanceId
+    disposePendingAuth()
+    const operationVersion = ++authOperationVersion
     setActionError(null)
     setStage("authorizing")
     try {
@@ -420,17 +476,18 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
       } else {
         await requestData((authClient as any).auth.remove({ providerID: providerId }), "auth.remove")
       }
-      await refreshAfterAuth(authClient)
-      resetFlow(null)
+      if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
+      await refreshAfterAuth(authClient, instanceId, operationVersion)
+      if (isCurrentOperation(operationVersion, instanceId, authClient)) resetFlow(null)
     } catch (error) {
+      if (!isCurrentOperation(operationVersion, instanceId, authClient)) return
       setActionError(extractProviderAuthErrorMessage(error, t("settings.providers.errors.removeFailed")))
-      setStage("error")
+      setStage("idle")
     }
   }
 
   function cancelOAuthWait() {
-    callbackAbortController?.abort()
-    callbackAbortController = null
+    disposePendingAuth()
     setStage("prompts")
     setAuthorization(null)
     setActionError(null)
@@ -445,27 +502,31 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
     return t("settings.providers.method.api")
   }
 
-  return (
-    <Dialog open={props.open} onOpenChange={handleModalOpenChange}>
-      <Dialog.Portal>
-        <Dialog.Overlay class="modal-overlay" />
-        <Dialog.Content class="modal-surface providers-manager-modal">
+  const content = () => (
+    <>
           <div class="providers-manager-header">
             <div class="settings-card-heading-with-icon">
               <PlugZap class="settings-card-heading-icon" />
               <div>
-                <Dialog.Title class="providers-manager-title">{t("settings.providers.title")}</Dialog.Title>
+                <Show
+                  when={!props.embedded}
+                  fallback={<h2 class="providers-manager-title">{t("settings.providers.title")}</h2>}
+                >
+                  <Dialog.Title class="providers-manager-title">{t("settings.providers.title")}</Dialog.Title>
+                </Show>
                 <p class="settings-card-subtitle">{t("settings.providers.subtitle")}</p>
               </div>
             </div>
-            <button type="button" class="selector-button selector-button-secondary settings-screen-close" onClick={() => handleModalOpenChange(false)} aria-label={t("settings.close")}>
-              <X class="w-4 h-4" />
-            </button>
+            <Show when={!props.embedded}>
+              <button type="button" class="selector-button selector-button-secondary settings-screen-close" onClick={() => handleModalOpenChange(false)} aria-label={t("settings.close")}>
+                <X class="w-4 h-4" />
+              </button>
+            </Show>
           </div>
 
           <div class="providers-manager-body">
             <Show when={!client()}>
-              <div class="settings-card-message">{t("settings.providers.empty.noInstance")}</div>
+              <div class="settings-card-message" role="status">{t("settings.providers.empty.noInstance")}</div>
             </Show>
 
             <Show when={client()}>
@@ -524,7 +585,10 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
               </div>
 
               <Show when={loadError()}>
-                <div class="settings-error-message">{loadError()}</div>
+                <div class="settings-error-message" role="alert">{loadError()}</div>
+              </Show>
+              <Show when={actionError()}>
+                <div class="settings-error-message" role="alert">{actionError()}</div>
               </Show>
 
               <Show when={activeProviderId()}>
@@ -563,6 +627,7 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
                         options={methodOptions()}
                         optionValue="value"
                         optionTextValue="label"
+                        disabled={stage() !== "prompts" && stage() !== "error"}
                         itemComponent={(itemProps) => <Select.Item item={itemProps.item} class="selector-option"><Select.ItemLabel class="selector-option-label">{itemProps.item.rawValue.label}</Select.ItemLabel></Select.Item>}
                       >
                         <Select.Trigger class="selector-trigger providers-method-trigger" aria-label={t("settings.providers.method.title")}>
@@ -581,9 +646,9 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
                   <Show when={selectedMethod().type === "oauth" && (stage() === "prompts" || stage() === "error" || stage() === "authorizing")}>
                     <div class="providers-form-stack">
                       <Show when={oauthPromptsUnsupported()}>
-                        <div class="settings-error-message">{t("settings.providers.oauth.promptsUnsupported")}</div>
+                        <div class="settings-error-message" role="alert">{t("settings.providers.oauth.promptsUnsupported")}</div>
                       </Show>
-                      <Show when={visiblePrompts().length === 0}><div class="settings-card-message">{t("settings.providers.oauth.noPrompts")}</div></Show>
+                      <Show when={visiblePrompts().length === 0}><div class="settings-card-message" role="status">{t("settings.providers.oauth.noPrompts")}</div></Show>
                       <For each={oauthPromptsUnsupported() ? [] : visiblePrompts()}>{(prompt) => (
                         <div class="providers-field">
                           <label class="settings-form-label" for={`provider-prompt-${prompt.key}`}>{prompt.message}</label>
@@ -598,8 +663,8 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
                     </div>
                   </Show>
 
-                  <Show when={stage() === "code"}><div class="providers-form-stack"><div class="providers-oauth-instructions"><ExternalLink class="providers-instructions-icon" /><span>{authorization()?.instructions || t("settings.providers.oauth.enterCode")}</span></div><label class="providers-field"><span class="settings-form-label">{t("settings.providers.oauth.codeLabel")}</span><input type="text" class="providers-input" value={code()} onInput={(event) => setCode(event.currentTarget.value)} placeholder={t("settings.providers.oauth.codePlaceholder")} autocomplete="one-time-code" /></label></div></Show>
-                  <Show when={stage() === "waiting"}><div class="providers-waiting-card"><Loader2 class="providers-spin-icon" /><div><div class="settings-toggle-title">{t("settings.providers.oauth.waitingTitle")}</div><div class="settings-toggle-caption">{authorization()?.instructions}</div></div><button type="button" class="selector-button selector-button-secondary providers-wait-cancel" onClick={cancelOAuthWait}>{t("settings.providers.oauth.cancelWait")}</button></div></Show>
+                  <Show when={stage() === "code"}><div class="providers-form-stack"><div class="providers-oauth-instructions"><ExternalLink class="providers-instructions-icon" /><span>{authorization()?.instructions || t("settings.providers.oauth.enterCode")}</span></div><label class="providers-field"><span class="settings-form-label">{t("settings.providers.oauth.codeLabel")}</span><input ref={(element) => { oauthCodeInput = element }} type="text" class="providers-input" value={code()} onInput={(event) => setCode(event.currentTarget.value)} placeholder={t("settings.providers.oauth.codePlaceholder")} autocomplete="one-time-code" /></label></div></Show>
+                  <Show when={stage() === "waiting"}><div class="providers-waiting-card" role="status"><Loader2 class="providers-spin-icon" /><div><div class="settings-toggle-title">{t("settings.providers.oauth.waitingTitle")}</div><div class="settings-toggle-caption">{authorization()?.instructions}</div></div><button type="button" class="selector-button selector-button-secondary providers-wait-cancel" onClick={cancelOAuthWait}>{t("settings.providers.oauth.cancelWait")}</button></div></Show>
                   <Show when={authorization() && (stage() === "code" || stage() === "waiting")}>
                     <div class="providers-oauth-actions">
                       <a href={authorization()?.url} target="_blank" rel="noopener noreferrer" class="selector-button selector-button-secondary providers-oauth-link">
@@ -615,10 +680,9 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
                     </div>
                   </Show>
                   <Show when={authorizationLaunchBlocked() && authorization()}>
-                    <div class="settings-card-message">{t("settings.providers.oauth.popupBlocked")}</div>
+                    <div class="settings-card-message" role="alert">{t("settings.providers.oauth.popupBlocked")}</div>
                   </Show>
-                  <Show when={stage() === "success"}><div class="providers-success-card"><Check class="providers-success-icon" /><span>{t("settings.providers.success")}</span></div></Show>
-                  <Show when={actionError()}><div class="settings-error-message">{actionError()}</div></Show>
+                  <Show when={stage() === "success"}><div class="providers-success-card" role="status"><Check class="providers-success-icon" /><span>{t("settings.providers.success")}</span></div></Show>
 
                   <div class="providers-actions-row">
                     <Show when={stage() === "code"} fallback={<button type="button" class="selector-button selector-button-primary" disabled={!canSubmit()} onClick={() => void submitAuth()}><Show when={stage() === "authorizing"} fallback={t("settings.providers.actions.continue")}><Loader2 class="providers-spin-icon" />{t("settings.providers.actions.working")}</Show></button>}>
@@ -630,19 +694,32 @@ export const ProviderManagerModal: Component<ProviderManagerModalProps> = (props
 
               <section class="providers-list-section">
                 <h3 class="settings-card-title">{t("settings.providers.configured.title")}</h3>
-                <Show when={loading()}><div class="providers-loading-row"><Loader2 class="providers-spin-icon" /><span>{t("settings.providers.loading")}</span></div></Show>
-                <Show when={!loading() && configuredProviders().length === 0}><div class="settings-card-message">{t("settings.providers.empty.noConfiguredProviders")}</div></Show>
+                <Show when={loading()}><div class="providers-loading-row" role="status"><Loader2 class="providers-spin-icon" /><span>{t("settings.providers.loading")}</span></div></Show>
+                <Show when={!loading() && configuredProviders().length === 0}><div class="settings-card-message" role="status">{t("settings.providers.empty.noConfiguredProviders")}</div></Show>
                 <div class="providers-grid">
                   <For each={configuredProviders()}>{(provider) => (
                     <article class="providers-card">
                       <div class="providers-card-main"><div class="providers-card-mark"><ShieldCheck class="providers-card-mark-icon" /></div><div class="providers-card-copy"><div class="providers-card-title-row"><h4 class="providers-card-title">{provider.name || provider.id}</h4></div><p class="providers-card-meta">{provider.id}</p><p class="providers-card-methods">{methodSummary(provider.id)}</p><p class="providers-card-source">{describeProviderSource(provider)}</p></div></div>
-                      <div class="providers-card-footer"><span class="providers-model-count">{provider.modelCount === 1 ? t("settings.providers.models.one", { count: provider.modelCount }) : t("settings.providers.models.other", { count: provider.modelCount })}</span><Show when={getDisconnectMode(provider) !== "disable-in-config"}><button type="button" class="selector-button selector-button-secondary providers-disconnect-button" disabled={getDisconnectMode(provider) === "not-disconnectable"} onClick={() => void disconnectProvider(provider.id)} title={getDisconnectMode(provider) === "not-disconnectable" ? t("settings.providers.source.env") : t("settings.providers.actions.disconnect")}>{t("settings.providers.actions.disconnect")}</button></Show></div>
+                       <div class="providers-card-footer"><span class="providers-model-count">{provider.modelCount === 1 ? t("settings.providers.models.one", { count: provider.modelCount }) : t("settings.providers.models.other", { count: provider.modelCount })}</span><Show when={getDisconnectMode(provider) !== "disable-in-config"}><button type="button" class="selector-button selector-button-secondary providers-disconnect-button" disabled={getDisconnectMode(provider) === "not-disconnectable" || stage() !== "idle"} onClick={() => void disconnectProvider(provider.id)} title={getDisconnectMode(provider) === "not-disconnectable" ? t("settings.providers.source.env") : t("settings.providers.actions.disconnect")}>{t("settings.providers.actions.disconnect")}</button></Show></div>
                     </article>
                   )}</For>
                 </div>
               </section>
             </Show>
           </div>
+    </>
+  )
+
+  if (props.embedded) {
+    return <div class="providers-manager-modal providers-manager-embedded">{content()}</div>
+  }
+
+  return (
+    <Dialog open={Boolean(props.open)} onOpenChange={handleModalOpenChange}>
+      <Dialog.Portal>
+        <Dialog.Overlay class="modal-overlay" />
+        <Dialog.Content class="modal-surface providers-manager-modal">
+          {content()}
         </Dialog.Content>
       </Dialog.Portal>
     </Dialog>
diff --git a/packages/ui/src/components/remote-server-dialog.tsx b/packages/ui/src/components/remote-server-dialog.tsx
new file mode 100644
index 00000000..dc5509f3
--- /dev/null
+++ b/packages/ui/src/components/remote-server-dialog.tsx
@@ -0,0 +1,80 @@
+import { Dialog } from "@kobalte/core/dialog"
+import { Loader2 } from "lucide-solid"
+import { createEffect, createSignal, Show, type Component } from "solid-js"
+import { useI18n } from "../lib/i18n"
+import type { RemoteServerInput } from "../lib/hooks/use-remote-server-profiles"
+
+interface RemoteServerDialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  onSubmit: (input: RemoteServerInput, openWindow: boolean) => Promise<unknown>
+}
+
+export const RemoteServerDialog: Component<RemoteServerDialogProps> = (props) => {
+  const { t } = useI18n()
+  const [name, setName] = createSignal("")
+  const [baseUrl, setBaseUrl] = createSignal("")
+  const [skipTlsVerify, setSkipTlsVerify] = createSignal(false)
+  const [error, setError] = createSignal<string | null>(null)
+  const [busy, setBusy] = createSignal(false)
+
+  createEffect(() => {
+    if (!props.open) return
+    setName("")
+    setBaseUrl("")
+    setSkipTlsVerify(false)
+    setError(null)
+  })
+
+  const submit = async (openWindow: boolean) => {
+    if (busy()) return
+    setBusy(true)
+    setError(null)
+    try {
+      await props.onSubmit({ name: name(), baseUrl: baseUrl(), skipTlsVerify: skipTlsVerify() }, openWindow)
+      props.onOpenChange(false)
+    } catch (submitError) {
+      setError(submitError instanceof Error ? submitError.message : String(submitError))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <Dialog open={props.open} onOpenChange={props.onOpenChange}>
+      <Dialog.Portal>
+        <Dialog.Overlay class="modal-overlay" />
+        <div class="fixed inset-0 z-[1300] flex items-center justify-center p-4">
+          <Dialog.Content class="modal-surface w-full max-w-lg p-6 flex flex-col gap-5" tabIndex={-1}>
+            <div>
+              <Dialog.Title class="text-xl font-semibold text-primary">{t("folderSelection.servers.dialog.title")}</Dialog.Title>
+              <Dialog.Description class="text-sm text-secondary mt-2">{t("folderSelection.servers.dialog.description")}</Dialog.Description>
+            </div>
+            <label class="flex flex-col gap-2 text-sm text-secondary">
+              <span>{t("folderSelection.servers.dialog.name")}</span>
+              <input class="selector-input w-full" value={name()} onInput={(event) => setName(event.currentTarget.value)} placeholder={t("folderSelection.servers.dialog.namePlaceholder")} />
+            </label>
+            <label class="flex flex-col gap-2 text-sm text-secondary">
+              <span>{t("folderSelection.servers.dialog.url")}</span>
+              <input class="selector-input w-full" value={baseUrl()} onInput={(event) => setBaseUrl(event.currentTarget.value)} placeholder={t("folderSelection.servers.dialog.urlPlaceholder")} />
+            </label>
+            <label class="flex items-start gap-3 text-sm text-secondary">
+              <input type="checkbox" checked={skipTlsVerify()} onChange={(event) => setSkipTlsVerify(event.currentTarget.checked)} />
+              <span>{t("folderSelection.servers.dialog.skipTls")}</span>
+            </label>
+            <Show when={error()}>{(message) => <p class="text-sm text-red-500 break-words">{message()}</p>}</Show>
+            <div class="flex items-center justify-end gap-3">
+              <button type="button" class="selector-button selector-button-secondary w-auto px-4" onClick={() => props.onOpenChange(false)}>{t("folderSelection.servers.dialog.cancel")}</button>
+              <button type="button" class="selector-button selector-button-secondary w-auto px-4" disabled={busy()} onClick={() => void submit(false)}>{t("folderSelection.servers.dialog.save")}</button>
+              <button type="button" class="selector-button selector-button-secondary w-auto px-4" disabled={busy()} onClick={() => void submit(true)}>
+                <Show when={busy()} fallback={<span>{t("folderSelection.servers.dialog.connect")}</span>}>
+                  <span class="inline-flex items-center gap-2"><Loader2 class="w-4 h-4 animate-spin" />{t("folderSelection.servers.dialog.connecting")}</span>
+                </Show>
+              </button>
+            </div>
+          </Dialog.Content>
+        </div>
+      </Dialog.Portal>
+    </Dialog>
+  )
+}
diff --git a/packages/ui/src/components/session-list-visibility.test.ts b/packages/ui/src/components/session-list-visibility.test.ts
new file mode 100644
index 00000000..b863c651
--- /dev/null
+++ b/packages/ui/src/components/session-list-visibility.test.ts
@@ -0,0 +1,29 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { isSessionListViewportAttached, shouldMountSessionList, shouldRenderSessionRows } from "./session-list-visibility"
+
+describe("session list visibility", () => {
+  it("does not mount inside a closed floating drawer", () => {
+    assert.equal(shouldMountSessionList("floating-closed"), false)
+    assert.equal(shouldMountSessionList("floating-open"), true)
+    assert.equal(shouldMountSessionList("pinned"), true)
+  })
+
+  it("keeps the error state exclusive from session rows", () => {
+    assert.equal(shouldRenderSessionRows(true, true), false)
+    assert.equal(shouldRenderSessionRows(false, true), true)
+    assert.equal(shouldRenderSessionRows(false, false), false)
+  })
+
+  it("waits for the drawer viewport to enter a live window", () => {
+    const viewport = (isConnected: boolean, defaultView: unknown) => ({
+      isConnected,
+      ownerDocument: { defaultView },
+    }) as Pick<HTMLElement, "isConnected" | "ownerDocument">
+
+    assert.equal(isSessionListViewportAttached(viewport(true, null)), false)
+    assert.equal(isSessionListViewportAttached(viewport(false, {})), false)
+    assert.equal(isSessionListViewportAttached(viewport(true, {})), true)
+  })
+})
diff --git a/packages/ui/src/components/session-list-visibility.ts b/packages/ui/src/components/session-list-visibility.ts
new file mode 100644
index 00000000..a7826eaf
--- /dev/null
+++ b/packages/ui/src/components/session-list-visibility.ts
@@ -0,0 +1,15 @@
+import type { DrawerViewState } from "./instance/shell/types"
+
+export function shouldMountSessionList(drawerState: DrawerViewState): boolean {
+  return drawerState !== "floating-closed"
+}
+
+export function isSessionListViewportAttached(
+  viewport: Pick<HTMLElement, "isConnected" | "ownerDocument">,
+): boolean {
+  return viewport.isConnected && Boolean(viewport.ownerDocument.defaultView)
+}
+
+export function shouldRenderSessionRows(hasError: boolean, hasContent: boolean): boolean {
+  return !hasError && hasContent
+}
diff --git a/packages/ui/src/components/session-list.tsx b/packages/ui/src/components/session-list.tsx
index aad207a8..db154943 100644
--- a/packages/ui/src/components/session-list.tsx
+++ b/packages/ui/src/components/session-list.tsx
@@ -1,9 +1,11 @@
-import { Component, For, Show, createSignal, createMemo, createEffect, JSX, onCleanup } from "solid-js"
+import { Component, Show, createSignal, createMemo, createEffect, JSX, on, onCleanup } from "solid-js"
+import { Virtualizer, type VirtualizerHandle } from "virtua/solid"
 import type { SessionStatus } from "../types/session"
 import type { SessionThread } from "../stores/session-state"
 import { getRetrySeconds, getSessionIdleFadeClass, getSessionRetry, getSessionStatus, shouldShowSessionStatus } from "../stores/session-status"
 import { Bot, User, Copy, Trash2, Pencil, ShieldAlert, ChevronDown, Search, Square, CheckSquare, MinusSquare, Split, RotateCw } from "lucide-solid"
 import KeyboardHint from "./keyboard-hint"
+import LoadErrorState from "./load-error-state"
 import SessionRenameDialog from "./session-rename-dialog"
 import { keyboardRegistry } from "../lib/keyboard-registry"
 import { showToastNotification } from "../lib/notifications"
@@ -11,27 +13,31 @@ import { useI18n } from "../lib/i18n"
 import { showConfirmDialog } from "../stores/alerts"
 import {
   deleteSession,
-  ensureSessionParentExpanded,
+  ensureSessionAncestorsExpanded,
   getVisibleSessionIds,
-  isSessionParentExpanded,
+  isSessionExpanded,
   loadMessages,
   loading,
   renameSession,
   sessions as sessionStateSessions,
   setActiveSessionFromList,
-  toggleSessionParentExpanded,
+  toggleSessionExpanded,
   loadMoreSessions,
   searchSessions,
   getSessionHasMore,
+  getSessionListError,
   clearSessionSearch,
+  fetchSessions,
   getSessionSearchQuery,
   getSessionSearchThreads,
   isSessionSearchLoading,
 } from "../stores/sessions"
 import { getGitRepoStatus, getWorktreeSlugForParentSession } from "../stores/worktrees"
+import { collectSessionThreadIds, findSessionThread, flattenVisibleSessionThreads, sortSessionIdsDeepestFirst } from "../stores/session-tree"
 import { getLogger } from "../lib/logger"
 import { copyToClipboard } from "../lib/clipboard"
 import { useConfig } from "../stores/preferences"
+import { isSessionListViewportAttached, shouldRenderSessionRows } from "./session-list-visibility"
 const log = getLogger("session")
 
 
@@ -65,6 +71,29 @@ const SessionList: Component<SessionListProps> = (props) => {
   const [selectedSessionIds, setSelectedSessionIds] = createSignal<Set<string>>(new Set())
   const [reloadingSessionIds, setReloadingSessionIds] = createSignal<Set<string>>(new Set())
   const [now, setNow] = createSignal(Date.now())
+  const [listEl, setListEl] = createSignal<HTMLDivElement>()
+  const [listViewportAttached, setListViewportAttached] = createSignal(false)
+  const [virtualizerHandle, setVirtualizerHandle] = createSignal<VirtualizerHandle>()
+  const [focusedSessionId, setFocusedSessionId] = createSignal<string>()
+  let attachmentFrame: number | undefined
+
+  const setListElement = (element: HTMLDivElement) => {
+    setListEl(element)
+    const detectAttachment = () => {
+      if (isSessionListViewportAttached(element)) {
+        attachmentFrame = undefined
+        setListViewportAttached(true)
+        return
+      }
+      setListViewportAttached(false)
+      if (typeof requestAnimationFrame !== "undefined") attachmentFrame = requestAnimationFrame(detectAttachment)
+    }
+    detectAttachment()
+  }
+
+  onCleanup(() => {
+    if (attachmentFrame !== undefined) cancelAnimationFrame(attachmentFrame)
+  })
 
   createEffect(() => {
     if (typeof window === "undefined") return
@@ -82,6 +111,13 @@ const SessionList: Component<SessionListProps> = (props) => {
   const isFetchingSessions = createMemo(() => {
     return loading().fetchingSessions.get(props.instanceId) ?? false
   })
+  const sessionListError = createMemo(() => getSessionListError(props.instanceId))
+
+  const handleRetrySessions = () => {
+    void fetchSessions(props.instanceId, { reset: true }).catch((error) => {
+      log.error("Failed to retry session list:", error)
+    })
+  }
 
   createEffect(() => {
     const el = sentinelEl()
@@ -96,7 +132,7 @@ const SessionList: Component<SessionListProps> = (props) => {
           })
         }
       },
-      { root: el.parentElement ?? null, rootMargin: "0px 0px 200px 0px" }
+      { root: listEl() ?? null, rootMargin: "0px 0px 200px 0px" }
     )
 
     observer.observe(el)
@@ -150,6 +186,16 @@ const SessionList: Component<SessionListProps> = (props) => {
     return sessionId.toLowerCase().includes(query)
   }
 
+  const filterThreadTree = (thread: SessionThread, query: string): SessionThread | null => {
+    const matchingChildren: SessionThread[] = []
+    for (const child of thread.children) {
+      const filteredChild = filterThreadTree(child, query)
+      if (filteredChild !== null) matchingChildren.push(filteredChild)
+    }
+    if (!sessionMatchesQuery(thread.session.id, query) && matchingChildren.length === 0) return null
+    return { ...thread, children: matchingChildren }
+  }
+
   const filteredThreads = createMemo<SessionThread[]>(() => {
     const query = normalizedQuery()
     if (!query) return props.threads
@@ -160,29 +206,46 @@ const SessionList: Component<SessionListProps> = (props) => {
       return getSessionSearchThreads(props.instanceId)
     }
 
-    const next: SessionThread[] = []
+    const result: SessionThread[] = []
     for (const thread of props.threads) {
-      const parentMatches = sessionMatchesQuery(thread.parent.id, query)
-      const matchingChildren = thread.children.filter((child) => sessionMatchesQuery(child.id, query))
-
-      if (!parentMatches && matchingChildren.length === 0) continue
-
-      next.push({
-        parent: thread.parent,
-        children: matchingChildren,
-        latestUpdated: thread.latestUpdated,
-      })
+      const filtered = filterThreadTree(thread, query)
+      if (filtered !== null) result.push(filtered)
     }
+    return result
+  })
 
-    return next
+  const visibleProjection = createMemo(() => {
+    const expandAll = Boolean(normalizedQuery())
+    const rows = flattenVisibleSessionThreads(
+      filteredThreads(),
+      (sessionId) => expandAll || isSessionExpanded(props.instanceId, sessionId),
+    )
+    const ids: string[] = []
+    const rowsById = new Map<string, (typeof rows)[number]>()
+    const indexById = new Map<string, number>()
+    rows.forEach((row, index) => {
+      ids.push(row.sessionId)
+      rowsById.set(row.sessionId, row)
+      indexById.set(row.sessionId, index)
+    })
+    return { ids, rowsById, indexById }
+  })
+  const keptMountedIndexes = createMemo(() => {
+    const sessionId = focusedSessionId()
+    if (!sessionId) return undefined
+    const index = visibleProjection().indexById.get(sessionId)
+    return index === undefined ? undefined : [index]
   })
 
   const allMatchingSessionIds = createMemo<string[]>(() => {
     const ids: string[] = []
-    for (const thread of filteredThreads()) {
-      ids.push(thread.parent.id)
-      for (const child of thread.children) ids.push(child.id)
+    const collectIds = (threads: SessionThread[]) => {
+      for (const thread of threads) {
+        ids.push(thread.session.id)
+        collectIds(thread.children)
+      }
     }
+    collectIds(filteredThreads())
     return ids
   })
 
@@ -206,14 +269,13 @@ const SessionList: Component<SessionListProps> = (props) => {
     const deleting = loading().deletingSession.get(props.instanceId)
     return deleting ? deleting.has(sessionId) : false
   }
- 
 
   const selectSession = (sessionId: string) => {
     const session = sessionStateSessions().get(props.instanceId)?.get(sessionId)
     // If the user selects a child session, make sure its parent thread is expanded.
     // For parent sessions we don't force expansion; user can collapse/expand freely.
     if (session?.parentId) {
-      ensureSessionParentExpanded(props.instanceId, session.parentId)
+      ensureSessionAncestorsExpanded(props.instanceId, session.id)
     }
 
     props.onSelect(sessionId)
@@ -360,21 +422,14 @@ const SessionList: Component<SessionListProps> = (props) => {
     })
   }
 
-  const getSelectableThreadIds = (parentId: string): string[] => {
-    const query = normalizedQuery()
-    const source = query ? filteredThreads() : props.threads
-    const thread = source.find((t) => t.parent.id === parentId)
-    if (!thread) return [parentId]
-    return [thread.parent.id, ...thread.children.map((c) => c.id)]
+  const getSelectableThreadIds = (sessionId: string): string[] => {
+    const source = normalizedQuery() ? filteredThreads() : props.threads
+    const thread = findSessionThread(source, sessionId)
+    return thread ? collectSessionThreadIds([thread]) : [sessionId]
   }
 
   const getAllSessionIdsInOrder = (threads: SessionThread[]): string[] => {
-    const ids: string[] = []
-    threads.forEach((thread) => {
-      ids.push(thread.parent.id)
-      thread.children.forEach((child) => ids.push(child.id))
-    })
-    return ids
+    return collectSessionThreadIds(threads)
   }
 
   const handleToggleSelectAll = (checked: boolean) => {
@@ -433,8 +488,9 @@ const SessionList: Component<SessionListProps> = (props) => {
       }
     }
 
+    const deletionOrder = sortSessionIdsDeepestFirst(sessionStateSessions().get(props.instanceId) ?? new Map(), selected)
     let failed = 0
-    for (const sessionId of selected) {
+    for (const sessionId of deletionOrder) {
       try {
         // eslint-disable-next-line no-await-in-loop
         await deleteSession(props.instanceId, sessionId)
@@ -457,38 +513,38 @@ const SessionList: Component<SessionListProps> = (props) => {
       })
     }
   }
- 
 
   const SessionRow: Component<{
-    sessionId: string
-    isChild?: boolean
-    isLastChild?: boolean
-    hasChildren?: boolean
+    session: SessionThread["session"]
+    depth: number
+    isLastChild: boolean
+    hasChildren: boolean
     expanded?: boolean
+    isLastRow: boolean
     onToggleExpand?: () => void
   }> = (rowProps) => {
-    const session = createMemo(() => sessionStateSessions().get(props.instanceId)?.get(rowProps.sessionId))
-    if (!session()) {
-      return <></>
-    }
+    const sessionId = () => rowProps.session.id
+    const isChild = () => rowProps.depth > 0
 
     const worktreeSlug = createMemo(() => {
-      if (rowProps.isChild) return "root"
-      return getWorktreeSlugForParentSession(props.instanceId, rowProps.sessionId)
+      if (isChild()) return "root"
+      return getWorktreeSlugForParentSession(props.instanceId, sessionId())
     })
 
     const showWorktreeBadge = createMemo(() => {
-      if (rowProps.isChild) return false
+      if (isChild()) return false
       if (getGitRepoStatus(props.instanceId) === false) return false
       const slug = worktreeSlug()
       return Boolean(slug) && slug !== "root"
     })
 
-    const isActive = () => props.activeSessionId === rowProps.sessionId
-    const title = () => session()?.title || t("sessionList.session.untitled")
-    const status = () => getSessionStatus(props.instanceId, rowProps.sessionId)
-    const retry = () => getSessionRetry(props.instanceId, rowProps.sessionId)
+    const isActive = () => props.activeSessionId === sessionId()
+    const title = () => rowProps.session.title || t("sessionList.session.untitled")
+    const status = () => getSessionStatus(props.instanceId, sessionId())
+    const interrupted = () => rowProps.session.generationRecovery === "interrupted"
+    const retry = () => getSessionRetry(props.instanceId, sessionId())
     const statusLabel = () => {
+      if (interrupted()) return t("sessionList.status.interrupted")
       const retryState = retry()
       if (retryState) {
         const seconds = getRetrySeconds(retryState.next, now())
@@ -503,20 +559,22 @@ const SessionList: Component<SessionListProps> = (props) => {
           return t("sessionList.status.idle")
       }
     }
-    const needsPermission = () => Boolean(session()?.pendingPermission)
-    const needsQuestion = () => Boolean((session() as any)?.pendingQuestion)
+    const needsPermission = () => Boolean(rowProps.session.pendingPermission)
+    const needsQuestion = () => Boolean((rowProps.session as any)?.pendingQuestion)
     const needsInput = () => needsPermission() || needsQuestion()
     const statusClassName = () => {
       if (needsInput()) return "session-permission"
+      if (interrupted()) return "session-interrupted"
       const base = `session-${retry() ? "retrying" : status()}`
-      const fadeClass = getSessionIdleFadeClass(props.instanceId, rowProps.sessionId)
+      const fadeClass = getSessionIdleFadeClass(props.instanceId, sessionId())
       return fadeClass ? `${base} ${fadeClass}` : base
     }
     const showStatus = () =>
+      interrupted() ||
       needsInput() ||
       shouldShowSessionStatus(
         props.instanceId,
-        rowProps.sessionId,
+        sessionId(),
         now(),
         preferences().keepUnseenSubagentIdleStatus,
       )
@@ -535,14 +593,10 @@ const SessionList: Component<SessionListProps> = (props) => {
       })
     }
  
-    const isSelected = () => selectedSessionIds().has(rowProps.sessionId)
+    const isSelected = () => selectedSessionIds().has(sessionId())
 
     const parentGroupState = createMemo(() => {
-      if (rowProps.isChild) {
-        return { checked: isSelected(), indeterminate: false, ids: [rowProps.sessionId] }
-      }
-
-      const ids = getSelectableThreadIds(rowProps.sessionId)
+      const ids = rowProps.hasChildren ? getSelectableThreadIds(sessionId()) : [sessionId()]
       const selected = selectedSessionIds()
       const selectedInGroup = ids.reduce((count, id) => (selected.has(id) ? count + 1 : count), 0)
       return {
@@ -558,12 +612,23 @@ const SessionList: Component<SessionListProps> = (props) => {
       rowCheckboxEl.indeterminate = parentGroupState().indeterminate
     })
 
+    const nestedStyle = () => {
+      if (!isChild()) return undefined
+      const visualDepth = Math.min(rowProps.depth, 6)
+      const indent = 1.375 + visualDepth * 0.875
+      return {
+        "--session-indent": `${indent}rem`,
+        "--session-connector-offset": `${indent - 0.875}rem`,
+      }
+    }
+
     return (
-      <div class="session-list-item group">
+      <div class={`session-list-item group ${rowProps.isLastRow ? "session-list-item-last" : ""}`}>
         <button
-          class={`session-item-base ${rowProps.isChild ? `session-item-child${rowProps.isLastChild ? " session-item-child-last" : ""} session-item-border-assistant session-item-kind-assistant` : "session-item-border-user session-item-kind-user"} ${isActive() ? "session-item-active" : "session-item-inactive"}`}
-          data-session-id={rowProps.sessionId}
-          onClick={() => selectSession(rowProps.sessionId)}
+          class={`session-item-base ${isChild() ? "session-item-nested" : ""} ${isChild() && rowProps.isLastChild ? "session-item-child-last" : ""} ${isChild() ? "session-item-border-assistant session-item-kind-assistant" : "session-item-border-user session-item-kind-user"} ${isActive() ? "session-item-active" : "session-item-inactive"}`}
+          style={nestedStyle()}
+          data-session-id={sessionId()}
+          onClick={() => selectSession(sessionId())}
           title={title()}
           role="button"
           aria-selected={isActive()}
@@ -587,15 +652,17 @@ const SessionList: Component<SessionListProps> = (props) => {
                 />
               </Show>
 
-              {rowProps.isChild ? <Bot class="w-4 h-4 flex-shrink-0" /> : <User class="w-4 h-4 flex-shrink-0" />}
+              <Show when={isChild()} fallback={<User class="w-4 h-4 flex-shrink-0" />}>
+                <Bot class="w-4 h-4 flex-shrink-0" />
+              </Show>
               <span class="session-item-title session-item-title--clamp" dir="auto">{title()}</span>
             </div>
           </div>
           <div class="session-item-row session-item-meta">
             <div class="flex items-center gap-2 min-w-0">
               <Show
-                when={rowProps.hasChildren && !rowProps.isChild}
-                fallback={rowProps.isChild ? null : <span class="session-item-expander session-item-expander--spacer" aria-hidden="true" />}
+                when={rowProps.hasChildren}
+                fallback={<span class="session-item-expander session-item-expander--spacer" aria-hidden="true" />}
               >
                 <span
                   class={`session-item-expander opacity-80 hover:opacity-100 ${isActive() ? "hover:bg-white/20" : "hover:bg-surface-hover"}`}
@@ -633,7 +700,7 @@ const SessionList: Component<SessionListProps> = (props) => {
             <div class="session-item-actions">
               <span
                 class={`session-item-close opacity-80 hover:opacity-100 ${isActive() ? "hover:bg-white/20" : "hover:bg-surface-hover"}`}
-                onClick={(event) => copySessionId(event, rowProps.sessionId)}
+                onClick={(event) => copySessionId(event, sessionId())}
                 role="button"
                 tabIndex={0}
                 aria-label={t("sessionList.actions.copyId.ariaLabel")}
@@ -643,14 +710,14 @@ const SessionList: Component<SessionListProps> = (props) => {
               </span>
               <span
                 class={`session-item-close opacity-80 hover:opacity-100 ${isActive() ? "hover:bg-white/20" : "hover:bg-surface-hover"}`}
-                onClick={(event) => handleReloadSession(event, rowProps.sessionId)}
+                onClick={(event) => handleReloadSession(event, sessionId())}
                 role="button"
                 tabIndex={0}
                 aria-label={t("sessionList.actions.reload.ariaLabel")}
                 title={t("sessionList.actions.reload.title")}
               >
                 <Show
-                  when={!isSessionReloading(rowProps.sessionId)}
+                  when={!isSessionReloading(sessionId())}
                   fallback={<RotateCw class="w-3 h-3 animate-spin" />}
                 >
                   <RotateCw class="w-3 h-3" />
@@ -660,7 +727,7 @@ const SessionList: Component<SessionListProps> = (props) => {
                 class={`session-item-close opacity-80 hover:opacity-100 ${isActive() ? "hover:bg-white/20" : "hover:bg-surface-hover"}`}
                 onClick={(event) => {
                   event.stopPropagation()
-                  openRenameDialog(rowProps.sessionId)
+                  openRenameDialog(sessionId())
                 }}
                 role="button"
                 tabIndex={0}
@@ -671,14 +738,14 @@ const SessionList: Component<SessionListProps> = (props) => {
               </span>
               <span
                 class={`session-item-close opacity-80 hover:opacity-100 ${isActive() ? "hover:bg-white/20" : "hover:bg-surface-hover"}`}
-                onClick={(event) => handleDeleteSession(event, rowProps.sessionId)}
+                onClick={(event) => handleDeleteSession(event, sessionId())}
                 role="button"
                 tabIndex={0}
                 aria-label={t("sessionList.actions.delete.ariaLabel")}
                 title={t("sessionList.actions.delete.title")}
               >
                 <Show
-                  when={!isSessionDeleting(rowProps.sessionId)}
+                  when={!isSessionDeleting(sessionId())}
                   fallback={
                     <svg class="animate-spin h-3 w-3" fill="none" viewBox="0 0 24 24">
                       <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
@@ -699,76 +766,25 @@ const SessionList: Component<SessionListProps> = (props) => {
       </div>
     )
   }
- 
-  const activeParentId = createMemo(() => {
-    const activeId = props.activeSessionId
-    if (!activeId || activeId === "info") return null
 
-    const activeSession = sessionStateSessions().get(props.instanceId)?.get(activeId)
-    if (!activeSession) return null
+  createEffect(on(
+    () => [props.activeSessionId, virtualizerHandle()] as const,
+    ([activeId, handle]) => {
+      if (!activeId || activeId === "info" || !handle) return
 
-    return activeSession.parentId ?? activeSession.id
-  })
+      const scroll = () => {
+        const index = visibleProjection().indexById.get(activeId)
+        if (index !== undefined) handle.scrollToIndex(index, { align: "nearest" })
+      }
+      if (typeof requestAnimationFrame === "undefined") {
+        scroll()
+        return
+      }
 
-  createEffect(() => {
-    // Keep the active child session visible by ensuring its parent is expanded.
-    // Don't force-expanding when the active session itself is a parent lets users collapse it.
-    const activeId = props.activeSessionId
-    if (!activeId || activeId === "info") return
-    const activeSession = sessionStateSessions().get(props.instanceId)?.get(activeId)
-    if (!activeSession) return
-    if (!activeSession.parentId) return
-    const parentId = activeParentId()
-    if (!parentId) return
-    ensureSessionParentExpanded(props.instanceId, parentId)
-  })
- 
-  const listEl = createSignal<HTMLElement | null>(null)
-
-  const escapeCss = (value: string) => {
-    if (typeof CSS !== "undefined" && typeof (CSS as any).escape === "function") {
-      return (CSS as any).escape(value)
-    }
-    return value.replace(/\\/g, "\\\\").replace(/\"/g, "\\\"")
-  }
-
-  const scrollActiveIntoView = (sessionId: string) => {
-    const root = listEl[0]()
-    if (!root) return
-
-    const selector = `[data-session-id="${escapeCss(sessionId)}"]`
-
-    const scrollNow = () => {
-      const target = root.querySelector(selector) as HTMLElement | null
-      if (!target) return
-      target.scrollIntoView({ block: "nearest", inline: "nearest" })
-    }
-
-    if (typeof requestAnimationFrame === "undefined") {
-      scrollNow()
-      return
-    }
-
-    // Wait a couple frames so expand/collapse DOM settles.
-    let raf1 = 0
-    let raf2 = 0
-    raf1 = requestAnimationFrame(() => {
-      raf2 = requestAnimationFrame(() => {
-        scrollNow()
-      })
-    })
-
-    onCleanup(() => {
-      if (raf1) cancelAnimationFrame(raf1)
-      if (raf2) cancelAnimationFrame(raf2)
-    })
-  }
-
-  createEffect(() => {
-    const activeId = props.activeSessionId
-    if (!activeId || activeId === "info") return
-    scrollActiveIntoView(activeId)
-  })
+      const frame = requestAnimationFrame(scroll)
+      onCleanup(() => cancelAnimationFrame(frame))
+    },
+  ))
 
   return (
     <div
@@ -846,35 +862,73 @@ const SessionList: Component<SessionListProps> = (props) => {
         </div>
       </Show>
 
-       <div class="session-list flex-1 overflow-y-auto" ref={(el) => listEl[1](el)}>
+       <div
+         class="session-list flex-1 overflow-y-auto"
+         ref={setListElement}
+         onFocusIn={(event) => {
+           const target = event.target
+           if (!(target instanceof Element)) return
+           const row = target.closest<HTMLElement>("[data-session-id]")
+           setFocusedSessionId(row?.dataset.sessionId)
+         }}
+         onFocusOut={(event) => {
+           const nextTarget = event.relatedTarget
+           if (nextTarget instanceof Node && listEl()?.contains(nextTarget)) return
+           setFocusedSessionId(undefined)
+         }}
+       >
 
-          <Show when={filteredThreads().length > 0}>
-            <div class="session-section">
-              <For each={filteredThreads()}>
+          <Show when={sessionListError()}>
+            {(error) => (
+              <LoadErrorState
+                variant="compact"
+                title={t("sessionList.loadError.title")}
+                error={error()}
+                retryLabel={t("sessionList.loadError.retry")}
+                onRetry={handleRetrySessions}
+              />
+            )}
+          </Show>
 
-               {(thread) => {
-                 const expanded = () => (normalizedQuery() ? true : isSessionParentExpanded(props.instanceId, thread.parent.id))
-                 return (
-                   <>
-                       <SessionRow
-                         sessionId={thread.parent.id}
-                         hasChildren={thread.children.length > 0}
-                         expanded={expanded()}
-                         onToggleExpand={() => toggleSessionParentExpanded(props.instanceId, thread.parent.id)}
-                       />
+          <Show when={!sessionListError() && isFetchingSessions() && visibleProjection().ids.length === 0}>
+            <div class="flex items-center justify-center p-4 text-xs text-muted" role="status">
+              <span class="animate-pulse">{t("sessionList.loading.initial")}</span>
+            </div>
+          </Show>
 
-                     <Show when={expanded() && thread.children.length > 0}>
-                       <For each={thread.children}>
-                         {(child, index) => (
-                           <SessionRow sessionId={child.id} isChild isLastChild={index() === thread.children.length - 1} />
-                         )}
-                       </For>
+          <Show when={shouldRenderSessionRows(
+            Boolean(sessionListError()),
+            listViewportAttached() && (visibleProjection().ids.length > 0 || hasMore() || isFetchingSessions()),
+          )}>
+           <div class="session-section">
+             <Show when={visibleProjection().ids.length > 0}>
+               <Virtualizer
+                 ref={setVirtualizerHandle}
+                 data={visibleProjection().ids}
+                 scrollRef={listEl()}
+                 bufferSize={400}
+                 keepMounted={keptMountedIndexes()}
+               >
+                 {(sessionId, index) => {
+                   const row = createMemo(() => visibleProjection().rowsById.get(sessionId))
+                   return (
+                     <Show when={row()}>
+                       {(current) => (
+                         <SessionRow
+                           session={current().thread.session}
+                           depth={current().depth}
+                           hasChildren={current().hasChildren}
+                           expanded={current().expanded}
+                           onToggleExpand={() => toggleSessionExpanded(props.instanceId, sessionId)}
+                           isLastChild={current().isLastChild}
+                           isLastRow={index() === visibleProjection().ids.length - 1 && !hasMore() && !isFetchingSessions()}
+                         />
+                       )}
                      </Show>
-                   </>
-                 )
-               }}
-             </For>
-
+                   )
+                 }}
+               </Virtualizer>
+             </Show>
              <Show when={hasMore() || isFetchingSessions()}>
                <div
                  ref={(el) => setSentinelEl(el)}
diff --git a/packages/ui/src/components/session/context-usage-panel.tsx b/packages/ui/src/components/session/context-usage-panel.tsx
index 7c69ea1f..68dd5cc4 100644
--- a/packages/ui/src/components/session/context-usage-panel.tsx
+++ b/packages/ui/src/components/session/context-usage-panel.tsx
@@ -53,7 +53,7 @@ const ContextUsagePanel: Component<ContextUsagePanelProps> = (props) => {
     return value > 0 ? value : 0
   })
 
-  const costDisplay = createMemo(() => `$${costValue().toFixed(2)}`)
+  const costDisplay = createMemo(() => info().isSubscriptionModel ? t("contextUsagePanel.included") : `$${costValue().toFixed(2)}`)
 
   return (
     <div class={`session-context-panel px-4 py-2 ${props.class ?? ""}`}>
diff --git a/packages/ui/src/components/session/provider-usage-panel.tsx b/packages/ui/src/components/session/provider-usage-panel.tsx
new file mode 100644
index 00000000..475998fb
--- /dev/null
+++ b/packages/ui/src/components/session/provider-usage-panel.tsx
@@ -0,0 +1,158 @@
+import { For, Show, createEffect, createMemo, createSignal, onCleanup, type Component } from "solid-js"
+
+import type { ProviderUsageResponse, ProviderUsageWindow } from "../../../../server/src/api-types"
+import { serverApi } from "../../lib/api-client"
+import { useI18n } from "../../lib/i18n"
+
+interface ProviderUsagePanelProps {
+  providerId: string
+  modelId: string
+}
+
+const REFRESH_INTERVAL_MS = 60_000
+
+const ProviderUsagePanel: Component<ProviderUsagePanelProps> = (props) => {
+  const { t } = useI18n()
+  const source = createMemo(() => {
+    const providerId = props.providerId.trim()
+    if (!providerId) return null
+    return { providerId, modelId: props.modelId.trim() }
+  })
+  const [usage, setUsage] = createSignal<ProviderUsageResponse | null>()
+  let requestId = 0
+
+  const refreshUsage = async (providerId: string, modelId: string, clear: boolean) => {
+    const currentRequestId = ++requestId
+    if (clear) setUsage(undefined)
+    try {
+      const response = await serverApi.fetchProviderUsage(providerId, modelId)
+      if (currentRequestId === requestId) setUsage(response)
+    } catch {
+      if (currentRequestId === requestId && usage() === undefined) setUsage(null)
+    }
+  }
+
+  createEffect(() => {
+    const current = source()
+    if (!current) {
+      requestId += 1
+      setUsage(undefined)
+      return
+    }
+    void refreshUsage(current.providerId, current.modelId, true)
+  })
+
+  const refreshTimer = setInterval(() => {
+    const current = source()
+    if (current) void refreshUsage(current.providerId, current.modelId, false)
+  }, REFRESH_INTERVAL_MS)
+  onCleanup(() => {
+    requestId += 1
+    clearInterval(refreshTimer)
+  })
+
+  const entries = createMemo(() => Object.entries(usage()?.windows ?? {}))
+
+  const windowLabel = (label: string) => {
+    const key = ({
+      "5h": "fiveHours",
+      "7d": "sevenDays",
+      "7d-sonnet": "sevenDaysSonnet",
+      "7d-opus": "sevenDaysOpus",
+      weekly: "weekly",
+      daily: "daily",
+      monthly: "monthly",
+      credits: "credits",
+      billing_cycle: "billingCycle",
+      session: "session",
+      premium: "premium",
+      chat: "chat",
+      completions: "completions",
+      "mcp-tools": "mcpTools",
+    } as Record<string, string>)[label]
+    return key ? t(`providerUsage.windows.${key}`) : label
+  }
+
+  const displayValue = (window: ProviderUsageWindow) => {
+    if (window.valueLabel) return window.valueLabel
+    if (window.usedPercent === null) return t("providerUsage.unavailableValue")
+    return t("providerUsage.usedPercent", { percent: Math.round(window.usedPercent) })
+  }
+
+  const resetLabel = (resetAt: number | null) => {
+    if (!resetAt) return null
+    const date = new Date(resetAt)
+    if (!Number.isFinite(date.getTime())) return null
+    return t("providerUsage.resets", { time: date.toLocaleString([], { dateStyle: "short", timeStyle: "short" }) })
+  }
+
+  const barColor = (percent: number | null) => {
+    if (percent !== null && percent >= 80) return "var(--status-error)"
+    if (percent !== null && percent >= 50) return "var(--status-warning)"
+    return "var(--status-success)"
+  }
+
+  return (
+    <div>
+      <Show when={usage() !== undefined} fallback={<div class="text-xs text-tertiary">{t("providerUsage.loading")}</div>}>
+        <Show when={usage()} fallback={<div class="text-xs text-tertiary">{t("providerUsage.unavailable")}</div>}>
+          {(data) => (
+            <Show
+              when={data().supported && data().configured && data().ok && entries().length > 0}
+              fallback={
+                <div class="text-xs text-tertiary">
+                  {t(
+                    !data().supported
+                      ? "providerUsage.unsupported"
+                      : !data().configured
+                        ? "providerUsage.notConfigured"
+                        : "providerUsage.unavailable",
+                  )}
+                </div>
+              }
+            >
+              <div class="space-y-2">
+                <For each={entries()}>
+                  {([label, window]) => (
+                    <div>
+                      <div class="mb-1 flex items-baseline justify-between gap-2 text-[11px] text-primary">
+                        <span class="font-medium">{windowLabel(label)}</span>
+                        <div class="flex min-w-0 items-baseline gap-1.5 text-right">
+                          <span class="shrink-0 font-medium">{displayValue(window)}</span>
+                          <Show when={resetLabel(window.resetAt)}>
+                            {(reset) => (
+                              <>
+                                <span class="text-tertiary" aria-hidden="true">·</span>
+                                <span class="truncate text-[10px] text-tertiary">{reset()}</span>
+                              </>
+                            )}
+                          </Show>
+                        </div>
+                      </div>
+                      <Show when={window.usedPercent !== null}>
+                        <div class="h-2 overflow-hidden border border-base" style={{ "background-color": "var(--surface-base)" }}>
+                          <div
+                            class="h-full transition-[width] duration-300"
+                            style={{ width: `${Math.max(0, Math.min(100, window.usedPercent ?? 0))}%`, "background-color": barColor(window.usedPercent) }}
+                            role="progressbar"
+                            aria-label={t("providerUsage.progressLabel", { window: windowLabel(label) })}
+                            aria-valuemin={0}
+                            aria-valuemax={100}
+                            aria-valuenow={Math.round(window.usedPercent ?? 0)}
+                          />
+                        </div>
+                      </Show>
+                    </div>
+                  )}
+                </For>
+              </div>
+            </Show>
+          )}
+        </Show>
+      </Show>
+      <div class="mt-2 truncate text-right text-sm font-semibold text-secondary">{usage()?.providerName ?? props.providerId}</div>
+    </div>
+  )
+}
+
+export default ProviderUsagePanel
diff --git a/packages/ui/src/components/session/session-bottom-follow-intent.test.ts b/packages/ui/src/components/session/session-bottom-follow-intent.test.ts
deleted file mode 100644
index 790b5978..00000000
--- a/packages/ui/src/components/session/session-bottom-follow-intent.test.ts
+++ /dev/null
@@ -1,56 +0,0 @@
-import assert from "node:assert/strict"
-import { describe, it } from "node:test"
-
-import { resolveSessionBottomFollowIntent, shouldClearSessionBottomFollowIntent } from "./session-bottom-follow-intent.ts"
-
-describe("session bottom follow intent", () => {
-  it("only exposes submit follow intent to the matching session", () => {
-    const intent = { sessionId: "session-a", token: 3, minItemCount: 12 }
-
-    assert.deepEqual(resolveSessionBottomFollowIntent(intent, "session-a"), {
-      token: 3,
-      minItemCount: 12,
-    })
-    assert.equal(resolveSessionBottomFollowIntent(intent, "session-b"), null)
-  })
-
-  it("clears submit follow intent only after the submitted exchange has rendered and stopped streaming", () => {
-    const intent = { sessionId: "session-a", token: 3, minItemCount: 12 }
-
-    assert.equal(
-      shouldClearSessionBottomFollowIntent(intent, {
-        sessionId: "session-a",
-        messageCount: 11,
-        streamingActive: false,
-      }),
-      false,
-    )
-
-    assert.equal(
-      shouldClearSessionBottomFollowIntent(intent, {
-        sessionId: "session-a",
-        messageCount: 12,
-        streamingActive: true,
-      }),
-      false,
-    )
-
-    assert.equal(
-      shouldClearSessionBottomFollowIntent(intent, {
-        sessionId: "session-a",
-        messageCount: 12,
-        streamingActive: false,
-      }),
-      true,
-    )
-
-    assert.equal(
-      shouldClearSessionBottomFollowIntent(intent, {
-        sessionId: "session-b",
-        messageCount: 12,
-        streamingActive: false,
-      }),
-      false,
-    )
-  })
-})
diff --git a/packages/ui/src/components/session/session-bottom-follow-intent.ts b/packages/ui/src/components/session/session-bottom-follow-intent.ts
deleted file mode 100644
index 2546cbc8..00000000
--- a/packages/ui/src/components/session/session-bottom-follow-intent.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import type { VirtualFollowBottomIntent } from "../virtual-follow-list"
-
-export interface SessionBottomFollowIntent extends VirtualFollowBottomIntent {
-  sessionId: string
-}
-
-export function resolveSessionBottomFollowIntent(
-  intent: SessionBottomFollowIntent | null,
-  sessionId: string,
-): VirtualFollowBottomIntent | null {
-  if (!intent || intent.sessionId !== sessionId) return null
-  return { token: intent.token, minItemCount: intent.minItemCount }
-}
-
-export function shouldClearSessionBottomFollowIntent(
-  intent: SessionBottomFollowIntent | null,
-  state: { sessionId: string; messageCount: number; streamingActive: boolean },
-) {
-  if (!intent) return false
-  if (intent.sessionId !== state.sessionId) return false
-  return state.messageCount >= (intent.minItemCount ?? 0) && !state.streamingActive
-}
diff --git a/packages/ui/src/components/session/session-bottom-pin-intent.test.ts b/packages/ui/src/components/session/session-bottom-pin-intent.test.ts
new file mode 100644
index 00000000..7a1fa9d5
--- /dev/null
+++ b/packages/ui/src/components/session/session-bottom-pin-intent.test.ts
@@ -0,0 +1,74 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { getSubmitBottomPinTargetCount, resolveSessionBottomPinIntent, shouldClearSessionBottomPinIntent } from "./session-bottom-pin-intent.ts"
+
+describe("session bottom pin intent", () => {
+  it("targets only the queued user prompt when submitting during active streaming", () => {
+    assert.equal(getSubmitBottomPinTargetCount(10, true), 11)
+    assert.equal(getSubmitBottomPinTargetCount(10, false), 12)
+  })
+
+  it("only exposes submit bottom pin intent to the matching session", () => {
+    const intent = { sessionId: "session-a", token: 3, minItemCount: 12, createdMessageCount: 10, observedStreaming: false }
+
+    assert.deepEqual(resolveSessionBottomPinIntent(intent, "session-a"), {
+      token: 3,
+      minItemCount: 12,
+    })
+    assert.equal(resolveSessionBottomPinIntent(intent, "session-b"), null)
+  })
+
+  it("clears submit bottom pin intent after the submitted exchange has rendered and stopped streaming", () => {
+    const intent = { sessionId: "session-a", token: 3, minItemCount: 12, createdMessageCount: 10, observedStreaming: false }
+
+    assert.equal(
+      shouldClearSessionBottomPinIntent(intent, {
+        sessionId: "session-a",
+        messageCount: 11,
+        streamingActive: false,
+      }),
+      false,
+    )
+
+    assert.equal(
+      shouldClearSessionBottomPinIntent(intent, {
+        sessionId: "session-a",
+        messageCount: 12,
+        streamingActive: true,
+      }),
+      false,
+    )
+
+    assert.equal(
+      shouldClearSessionBottomPinIntent(intent, {
+        sessionId: "session-a",
+        messageCount: 12,
+        streamingActive: false,
+      }),
+      true,
+    )
+
+    assert.equal(
+      shouldClearSessionBottomPinIntent(intent, {
+        sessionId: "session-b",
+        messageCount: 12,
+        streamingActive: false,
+      }),
+      false,
+    )
+  })
+
+  it("clears a submitted turn that stopped streaming before the optimistic count was reached", () => {
+    const intent = { sessionId: "session-a", token: 3, minItemCount: 12, createdMessageCount: 10, observedStreaming: true }
+
+    assert.equal(
+      shouldClearSessionBottomPinIntent(intent, {
+        sessionId: "session-a",
+        messageCount: 11,
+        streamingActive: false,
+      }),
+      true,
+    )
+  })
+})
diff --git a/packages/ui/src/components/session/session-bottom-pin-intent.ts b/packages/ui/src/components/session/session-bottom-pin-intent.ts
new file mode 100644
index 00000000..f96ad689
--- /dev/null
+++ b/packages/ui/src/components/session/session-bottom-pin-intent.ts
@@ -0,0 +1,30 @@
+import type { VirtualExplicitBottomPinIntent } from "../virtual-follow-list"
+
+export interface SessionBottomPinIntent extends VirtualExplicitBottomPinIntent {
+  sessionId: string
+  createdMessageCount: number
+  observedStreaming: boolean
+}
+
+export function getSubmitBottomPinTargetCount(messageCount: number, streamingActive: boolean) {
+  return messageCount + (streamingActive ? 1 : 2)
+}
+
+export function resolveSessionBottomPinIntent(
+  intent: SessionBottomPinIntent | null,
+  sessionId: string,
+): VirtualExplicitBottomPinIntent | null {
+  if (!intent || intent.sessionId !== sessionId) return null
+  return { token: intent.token, minItemCount: intent.minItemCount }
+}
+
+export function shouldClearSessionBottomPinIntent(
+  intent: SessionBottomPinIntent | null,
+  state: { sessionId: string; messageCount: number; streamingActive: boolean },
+) {
+  if (!intent) return false
+  if (intent.sessionId !== state.sessionId) return false
+  if (state.streamingActive) return false
+  if (state.messageCount >= (intent.minItemCount ?? 0)) return true
+  return intent.observedStreaming && state.messageCount > intent.createdMessageCount
+}
diff --git a/packages/ui/src/components/session/session-view.tsx b/packages/ui/src/components/session/session-view.tsx
index 3b8bc371..af11017a 100644
--- a/packages/ui/src/components/session/session-view.tsx
+++ b/packages/ui/src/components/session/session-view.tsx
@@ -7,8 +7,8 @@ import { messageStoreBus } from "../../stores/message-v2/bus"
 import PromptInput from "../prompt-input"
 import PromptAttachmentsBar from "../prompt-input/PromptAttachmentsBar"
 import { getAttachments, removeAttachment } from "../../stores/attachments"
-import { instances } from "../../stores/instances"
-import { loadMessages, sendMessage, forkSession, renameSession, isSessionMessagesLoading, getSessionMessagesLoadError, markSessionIdleSeen, setActiveParentSession, setActiveSession, runShellCommand, abortSession } from "../../stores/sessions"
+import { instances, waitForInstanceWorkspaceMetadataHydration } from "../../stores/instances"
+import { loadMessages, sendMessage, forkSession, renameSession, isSessionMessagesLoading, getSessionMessagesLoadError, markSessionIdleSeen, ensureSessionAncestorsExpanded, setActiveSessionFromList, runShellCommand, abortSession } from "../../stores/sessions"
 import { clearSessionIdleFade, IDLE_STATUS_VISIBILITY_MS, getSessionStatus, isSessionBusy as getSessionBusyStatus, markSessionIdleFadeStarted } from "../../stores/session-status"
 import { deleteMessage } from "../../stores/session-actions"
 import { showAlertDialog } from "../../stores/alerts"
@@ -21,7 +21,8 @@ import { useConfig } from "../../stores/preferences"
 import { closeSessionPreview, getSessionPreview, showSessionChat } from "../../stores/session-previews"
 import { SessionPreviewView } from "../session-preview-view"
 import { isSnapshotAutoFollowing } from "../virtual-follow-behavior"
-import { resolveSessionBottomFollowIntent, shouldClearSessionBottomFollowIntent, type SessionBottomFollowIntent } from "./session-bottom-follow-intent"
+import { getSubmitBottomPinTargetCount, resolveSessionBottomPinIntent, shouldClearSessionBottomPinIntent, type SessionBottomPinIntent } from "./session-bottom-pin-intent"
+import { focusConversationStream } from "../focus-conversation"
 
 const log = getLogger("session")
 
@@ -37,6 +38,8 @@ interface SessionViewProps {
   escapeInDebounce: boolean
   isPhoneLayout?: boolean
   compactPromptLayout?: boolean
+  focusConversationOnActivate?: boolean
+  onConversationFocusHandled?: () => void
   showSidebarToggle?: boolean
   onSidebarToggle?: () => void
   forceCompactStatusLayout?: boolean
@@ -61,7 +64,6 @@ export const SessionView: Component<SessionViewProps> = (props) => {
     if (!currentSession) return false
     return getSessionStatus(props.instanceId, currentSession.id) === "working"
   })
-
   const sessionNeedsInput = createMemo(() => {
     const currentSession = session()
     if (!currentSession) return false
@@ -81,8 +83,8 @@ export const SessionView: Component<SessionViewProps> = (props) => {
   let scrollToBottomHandle: (() => void) | undefined
   let rootRef: HTMLDivElement | undefined
   const pendingIdleSeenTimers = new Set<string>()
-  const [submitBottomFollowIntent, setSubmitBottomFollowIntent] = createSignal<SessionBottomFollowIntent | null>(null)
-  let submitBottomFollowIntentSequence = 0
+  const [submitBottomPinIntent, setSubmitBottomPinIntent] = createSignal<SessionBottomPinIntent | null>(null)
+  let submitBottomPinIntentSequence = 0
 
   function shouldScrollToBottomOnActivate() {
     const current = session()
@@ -105,23 +107,45 @@ export const SessionView: Component<SessionViewProps> = (props) => {
     return true
   }
 
-  function startSubmitBottomFollowIntent(minItemCount: number) {
-    submitBottomFollowIntentSequence += 1
-    setSubmitBottomFollowIntent({ sessionId: props.sessionId, token: submitBottomFollowIntentSequence, minItemCount })
+  function startSubmitBottomPinIntent(
+    minItemCount: number,
+    options?: { createdMessageCount?: number; preserveObservedStreaming?: boolean },
+  ) {
+    submitBottomPinIntentSequence += 1
+    const previous = submitBottomPinIntent()
+    const createdMessageCount = options?.createdMessageCount ?? messageStore().getSessionMessageIds(props.sessionId).length
+    const shouldPreserveObservedStreaming = Boolean(
+      options?.preserveObservedStreaming &&
+      previous?.sessionId === props.sessionId &&
+      previous.createdMessageCount === createdMessageCount,
+    )
+    const intent: SessionBottomPinIntent = {
+      sessionId: props.sessionId,
+      token: submitBottomPinIntentSequence,
+      minItemCount,
+      createdMessageCount,
+      observedStreaming: shouldPreserveObservedStreaming ? previous?.observedStreaming === true : false,
+    }
+    setSubmitBottomPinIntent(intent)
+    return intent
   }
 
-  function forceSubmittedExchangeToBottom(minItemCount: number) {
-    startSubmitBottomFollowIntent(minItemCount)
+  function forceSubmittedExchangeToBottom(
+    minItemCount: number,
+    options?: { createdMessageCount?: number; preserveObservedStreaming?: boolean },
+  ) {
+    const intent = startSubmitBottomPinIntent(minItemCount, options)
     scrollToBottomHandle?.()
+    return intent
   }
 
-  const activeSubmitBottomFollowIntent = createMemo(() => {
-    const intent = submitBottomFollowIntent()
+  const activeSubmitBottomPinIntent = createMemo(() => {
+    const intent = submitBottomPinIntent()
     const currentSession = session()
     if (!intent || !currentSession) return null
 
     const messageCount = messageStore().getSessionMessageIds(currentSession.id).length
-    if (shouldClearSessionBottomFollowIntent(intent, {
+    if (shouldClearSessionBottomPinIntent(intent, {
       sessionId: currentSession.id,
       messageCount,
       streamingActive: sessionStreamingActive(),
@@ -129,7 +153,7 @@ export const SessionView: Component<SessionViewProps> = (props) => {
       return null
     }
 
-    return resolveSessionBottomFollowIntent(intent, currentSession.id)
+    return resolveSessionBottomPinIntent(intent, currentSession.id)
   })
 
   function getSeenIdleEntries(currentSession: Session, keepUnseenSubagentIdleStatus: boolean): Array<{ id: string; idleSince: number }> {
@@ -141,7 +165,7 @@ export const SessionView: Component<SessionViewProps> = (props) => {
 
     if (currentSession.parentId === null && !keepUnseenSubagentIdleStatus) {
       for (const child of props.activeSessions.values()) {
-        if (child.parentId !== currentSession.id) continue
+        if (child.id === currentSession.id) continue
         if (child.status !== "idle") continue
         if (typeof child.idleSince !== "number") continue
         entries.push({ id: child.id, idleSince: child.idleSince })
@@ -151,6 +175,14 @@ export const SessionView: Component<SessionViewProps> = (props) => {
     return entries
   }
 
+  createEffect(
+    on(
+      () => props.sessionId,
+      () => setSubmitBottomPinIntent(null),
+      { defer: true },
+    ),
+  )
+
   createEffect(
     on(
       () => props.isActive,
@@ -164,17 +196,22 @@ export const SessionView: Component<SessionViewProps> = (props) => {
   )
 
   createEffect(() => {
-    const intent = submitBottomFollowIntent()
+    const intent = submitBottomPinIntent()
     const currentSession = session()
     if (!intent || !currentSession) return
 
+    if (sessionStreamingActive() && intent.sessionId === currentSession.id && !intent.observedStreaming) {
+      setSubmitBottomPinIntent({ ...intent, observedStreaming: true })
+      return
+    }
+
     const messageCount = messageStore().getSessionMessageIds(currentSession.id).length
-    if (shouldClearSessionBottomFollowIntent(intent, {
+    if (shouldClearSessionBottomPinIntent(intent, {
       sessionId: currentSession.id,
       messageCount,
       streamingActive: sessionStreamingActive(),
     })) {
-      setSubmitBottomFollowIntent(null)
+      setSubmitBottomPinIntent(null)
     }
   })
 
@@ -188,13 +225,10 @@ export const SessionView: Component<SessionViewProps> = (props) => {
       if (pendingIdleSeenTimers.has(timerKey)) continue
       pendingIdleSeenTimers.add(timerKey)
       markSessionIdleFadeStarted(props.instanceId, entry.id)
+      markSessionIdleSeen(props.instanceId, entry.id)
 
       window.setTimeout(() => {
         pendingIdleSeenTimers.delete(timerKey)
-        const latestEntry = props.activeSessions.get(entry.id)
-        if (latestEntry?.status === "idle" && latestEntry.idleSince === entry.idleSince) {
-          markSessionIdleSeen(props.instanceId, entry.id)
-        }
         clearSessionIdleFade(props.instanceId, entry.id, entry.idleSince)
       }, IDLE_STATUS_VISIBILITY_MS)
     }
@@ -205,13 +239,13 @@ export const SessionView: Component<SessionViewProps> = (props) => {
       () => props.isActive,
       (isActive) => {
         if (!isActive) {
+          if (props.focusConversationOnActivate) props.onConversationFocusHandled?.()
           clearConversationPlaybackForSession(props.instanceId, props.sessionId)
           return
         }
-        if (!isActive) return
 
         // On phones, focusing the prompt on session switch is disruptive (it raises the OSK).
-        if (props.isPhoneLayout) return
+        if (props.isPhoneLayout && !props.focusConversationOnActivate) return
 
         // Don't steal focus from other inputs (command palette, dialogs, selectors, etc.)
         if (typeof document === "undefined") return
@@ -229,6 +263,19 @@ export const SessionView: Component<SessionViewProps> = (props) => {
         // Defer until the session pane is visible and the textarea is mounted.
         requestAnimationFrame(() => {
           requestAnimationFrame(() => {
+            if (!props.isActive) return
+            if (props.focusConversationOnActivate) {
+              const activeElement = document.activeElement
+              const focusIsUnclaimed =
+                !activeElement || activeElement === document.body || activeElement === document.documentElement
+              const modalIsOpen = Boolean(document.querySelector('[role="dialog"][aria-modal="true"]'))
+              if (focusIsUnclaimed && !modalIsOpen && focusConversationStream(rootRef)) {
+                props.onConversationFocusHandled?.()
+                return
+              }
+              props.onConversationFocusHandled?.()
+              if (!focusIsUnclaimed || modalIsOpen) return
+            }
             if (promptInputApi) {
               promptInputApi.focus()
               return
@@ -250,10 +297,16 @@ export const SessionView: Component<SessionViewProps> = (props) => {
   )
 
   createEffect(() => {
+    if (!props.isActive) return
     const currentSession = session()
-    if (currentSession) {
-      loadMessages(props.instanceId, currentSession.id).catch((error) => log.error("Failed to load messages", error))
-    }
+    if (!currentSession) return
+    const sessionId = currentSession.id
+    void waitForInstanceWorkspaceMetadataHydration(props.instanceId)
+      .then(() => {
+        if (!props.isActive || session()?.id !== sessionId) return
+        return loadMessages(props.instanceId, sessionId)
+      })
+      .catch((error) => log.error("Failed to load messages", error))
   })
 
   function handleReloadMessages() {
@@ -306,17 +359,24 @@ export const SessionView: Component<SessionViewProps> = (props) => {
       pendingCommentText = `${pendingCommentText ?? ""}${markdown}`
     }
   }
- 
+
   async function handleSendMessage(prompt: string, attachments: Attachment[]) {
     const messageCount = messageStore().getSessionMessageIds(props.sessionId).length
-    const submittedExchangeTargetCount = messageCount + 2
-    forceSubmittedExchangeToBottom(submittedExchangeTargetCount)
+    const submittedExchangeTargetCount = getSubmitBottomPinTargetCount(messageCount, sessionStreamingActive())
+    const initialPinIntent = forceSubmittedExchangeToBottom(submittedExchangeTargetCount, { createdMessageCount: messageCount })
     try {
       await sendMessage(props.instanceId, props.sessionId, prompt, attachments)
       const latestMessageCount = messageStore().getSessionMessageIds(props.sessionId).length
-      forceSubmittedExchangeToBottom(Math.max(submittedExchangeTargetCount, latestMessageCount))
+      if (latestMessageCount < submittedExchangeTargetCount && !sessionStreamingActive()) {
+        setSubmitBottomPinIntent(null)
+      } else if (submitBottomPinIntent()?.token === initialPinIntent.token) {
+        forceSubmittedExchangeToBottom(Math.max(submittedExchangeTargetCount, latestMessageCount), {
+          createdMessageCount: messageCount,
+          preserveObservedStreaming: true,
+        })
+      }
     } catch (error) {
-      setSubmitBottomFollowIntent(null)
+      setSubmitBottomPinIntent(null)
       throw error
     }
   }
@@ -434,11 +494,8 @@ export const SessionView: Component<SessionViewProps> = (props) => {
         log.error("Failed to rename forked session", error)
       })
 
-      const parentToActivate = forkedSession.parentId ?? forkedSession.id
-      setActiveParentSession(props.instanceId, parentToActivate)
-      if (forkedSession.parentId) {
-        setActiveSession(props.instanceId, forkedSession.id)
-      }
+      ensureSessionAncestorsExpanded(props.instanceId, forkedSession.id)
+      setActiveSessionFromList(props.instanceId, forkedSession.id)
 
       await loadMessages(props.instanceId, forkedSession.id).catch((error) => log.error("Failed to load forked session messages", error))
 
@@ -481,7 +538,8 @@ export const SessionView: Component<SessionViewProps> = (props) => {
                   loadError={messagesLoadError()}
                   onReloadMessages={handleReloadMessages}
                   sessionStreamingActive={sessionStreamingActive()}
-                  bottomFollowIntent={activeSubmitBottomFollowIntent()}
+                  explicitBottomPinIntent={activeSubmitBottomPinIntent()}
+                  onExplicitBottomPinCancelled={() => setSubmitBottomPinIntent(null)}
                   onRevert={handleRevert}
                   onDeleteMessagesUpTo={handleDeleteMessagesUpTo}
                   onFork={handleFork}
diff --git a/packages/ui/src/components/settings-screen.tsx b/packages/ui/src/components/settings-screen.tsx
index 989bfe5b..adc07b77 100644
--- a/packages/ui/src/components/settings-screen.tsx
+++ b/packages/ui/src/components/settings-screen.tsx
@@ -1,6 +1,6 @@
 import { Dialog } from "@kobalte/core/dialog"
 import { Select } from "@kobalte/core/select"
-import { Settings, Bell, ChevronDown, FileCog, Info, MonitorUp, Paintbrush, Terminal, Volume2, Globe, X } from "lucide-solid"
+import { Settings, Bell, ChevronDown, FileCog, Globe, Info, MessageSquare, MonitorUp, PlugZap, SlidersHorizontal, Terminal, Volume2, X } from "lucide-solid"
 import { createMemo, For, type Component } from "solid-js"
 import { useI18n } from "../lib/i18n"
 import {
@@ -10,13 +10,17 @@ import {
   setActiveSettingsSection,
   type SettingsSectionId,
 } from "../stores/settings-screen"
-import { AppearanceSettingsSection } from "./settings/appearance-settings-section"
+import { GeneralSettingsSection } from "./settings/general-settings-section"
+import { ChatSettingsSection } from "./settings/chat-settings-section"
 import { InfoSettingsSection } from "./settings/info-settings-section"
 import { NotificationsSettingsSection } from "./settings/notifications-settings-section"
+import { SpeechSettingsSection } from "./settings/speech-settings-section"
+import { ProvidersSettingsSection } from "./settings/providers-settings-section"
 import { OpenCodeSettingsSection } from "./settings/opencode-settings-section"
+import { AdvancedSettingsSection } from "./settings/advanced-settings-section"
 import { ConfigFilesSettingsSection } from "./settings/config-files-settings-section"
 import { RemoteAccessSettingsSection } from "./settings/remote-access-settings-section"
-import { SpeechSettingsSection } from "./settings/speech-settings-section"
+import { SavedRemoteServersCard } from "./settings/saved-remote-servers-card"
 import { SideCarsSettingsSection } from "./settings/sidecars-settings-section"
 import { canOpenRemoteWindows } from "../lib/runtime-env"
 import { confirmSettingsDiscard } from "../stores/settings-dirty-guard"
@@ -32,19 +36,20 @@ export const SettingsScreen: Component = () => {
 
   const sections = createMemo(() => {
     const items: SettingsSectionOption[] = [
-      { id: "appearance", icon: Paintbrush, label: t("settings.nav.appearance") },
+      { id: "general", icon: SlidersHorizontal, label: t("settings.nav.general") },
+      { id: "chat", icon: MessageSquare, label: t("settings.nav.chat") },
       { id: "notifications", icon: Bell, label: t("settings.nav.notifications") },
       { id: "speech", icon: Volume2, label: t("settings.nav.speech") },
-      { id: "sidecars", icon: Globe, label: t("settings.nav.sidecars") },
       { id: "opencode", icon: Terminal, label: t("settings.nav.opencode") },
+      { id: "providers", icon: PlugZap, label: t("settings.nav.providers") },
+      { id: "sidecars", icon: Globe, label: t("settings.nav.sidecars") },
       { id: "config-files", icon: FileCog, label: t("settings.nav.configFiles") },
+      { id: "advanced", icon: Settings, label: t("settings.nav.advanced") },
       { id: "info", icon: Info, label: t("settings.nav.info") },
     ]
-
     if (canOpenRemoteWindows()) {
-      items.splice(2, 0, { id: "remote", icon: MonitorUp, label: t("settings.nav.remote") })
+      items.splice(4, 0, { id: "remote", icon: MonitorUp, label: t("settings.nav.remote") })
     }
-
     return items
   })
 
@@ -52,23 +57,34 @@ export const SettingsScreen: Component = () => {
 
   const renderSection = () => {
     switch (activeSettingsSection()) {
+      case "chat":
+        return <ChatSettingsSection />
       case "notifications":
         return <NotificationsSettingsSection />
-      case "remote":
-        return canOpenRemoteWindows() ? <RemoteAccessSettingsSection /> : <AppearanceSettingsSection />
       case "speech":
         return <SpeechSettingsSection />
-      case "sidecars":
-        return <SideCarsSettingsSection />
+      case "remote":
+        return canOpenRemoteWindows() ? (
+          <div class="settings-section-stack">
+            <RemoteAccessSettingsSection />
+            <SavedRemoteServersCard />
+          </div>
+        ) : <GeneralSettingsSection />
       case "opencode":
         return <OpenCodeSettingsSection />
+      case "providers":
+        return <ProvidersSettingsSection />
+      case "sidecars":
+        return <SideCarsSettingsSection />
       case "config-files":
         return <ConfigFilesSettingsSection />
+      case "advanced":
+        return <AdvancedSettingsSection />
       case "info":
         return <InfoSettingsSection />
-      case "appearance":
+      case "general":
       default:
-        return <AppearanceSettingsSection />
+        return <GeneralSettingsSection />
     }
   }
 
@@ -171,6 +187,7 @@ export const SettingsScreen: Component = () => {
                         type="button"
                         class="settings-nav-button"
                         data-selected={activeSettingsSection() === section.id ? "true" : "false"}
+                        aria-current={activeSettingsSection() === section.id ? "page" : undefined}
                         onClick={() => void handleSectionChange(section.id)}
                       >
                         <Icon class="settings-nav-button-icon" />
diff --git a/packages/ui/src/components/settings/advanced-settings-section.tsx b/packages/ui/src/components/settings/advanced-settings-section.tsx
new file mode 100644
index 00000000..6de2da02
--- /dev/null
+++ b/packages/ui/src/components/settings/advanced-settings-section.tsx
@@ -0,0 +1,40 @@
+import { createMemo, type Component } from "solid-js"
+import { useI18n } from "../../lib/i18n"
+import { getBehaviorSettings } from "../../lib/settings/behavior-registry"
+import { useConfig } from "../../stores/preferences"
+import EnvironmentVariablesEditor from "../environment-variables-editor"
+import { BehaviorSettingRows } from "./behavior-setting-rows"
+
+export const AdvancedSettingsSection: Component = () => {
+  const { t } = useI18n()
+  const config = useConfig()
+  const advancedSettings = createMemo(() =>
+    getBehaviorSettings(config).filter(
+      (setting) =>
+        setting.id === "behavior.autoCleanupBlankSessions" ||
+        setting.id === "behavior.keepUnseenSubagentIdleStatus" ||
+        setting.id === "behavior.tauriNativeEventTransport",
+    ),
+  )
+
+  return (
+    <div class="settings-section-stack">
+      <div class="settings-card">
+        <div class="settings-card-header">
+          <div>
+            <h3 class="settings-card-title">{t("advancedSettings.environmentVariables.title")}</h3>
+            <p class="settings-card-subtitle">{t("advancedSettings.environmentVariables.subtitle")}</p>
+          </div>
+          <span class="settings-scope-badge settings-scope-badge-server">{t("settings.scope.server")}</span>
+        </div>
+        <EnvironmentVariablesEditor />
+      </div>
+
+      <div class="settings-card">
+        <div class="settings-stack">
+          <BehaviorSettingRows settings={advancedSettings} preferences={config.preferences} />
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/packages/ui/src/components/settings/appearance-settings-section.tsx b/packages/ui/src/components/settings/appearance-settings-section.tsx
deleted file mode 100644
index ea3172de..00000000
--- a/packages/ui/src/components/settings/appearance-settings-section.tsx
+++ /dev/null
@@ -1,435 +0,0 @@
-import { Select } from "@kobalte/core/select"
-import { createEffect, createMemo, createSignal, For, type Component } from "solid-js"
-import { Check, ChevronDown, Laptop, Moon, Sun } from "lucide-solid"
-import { useI18n } from "../../lib/i18n"
-import { useTheme, type ThemeMode } from "../../lib/theme"
-import { useConfig, type ExpansionPreference, type ToolCallExpansionPreset } from "../../stores/preferences"
-import { getBehaviorSettings, type BehaviorSetting } from "../../lib/settings/behavior-registry"
-import {
-  buildToolExpansionPresetDefaults,
-  getConfigurableToolEntries,
-  OTHER_TOOL_NAME,
-  THINKING_EXPANSION_PRESETS,
-} from "../tool-call/tool-registry"
-
-const themeModeOptions: Array<{ value: ThemeMode; icon: typeof Laptop }> = [
-  { value: "system", icon: Laptop },
-  { value: "light", icon: Sun },
-  { value: "dark", icon: Moon },
-]
-
-const toolExpansionPresetOptions: ToolCallExpansionPreset[] = ["minimal", "balanced", "detailed", "everything"]
-
-export const AppearanceSettingsSection: Component = () => {
-  const { t } = useI18n()
-  const { themeMode, setThemeMode } = useTheme()
-  const {
-    preferences,
-    useTauriNativeEventTransport,
-    setUseTauriNativeEventTransport,
-    updatePreferences,
-    toggleShowThinkingBlocks,
-    toggleKeyboardShortcutHints,
-    toggleShowMessageTimeline,
-    toggleShowTimelineTools,
-    toggleUsageMetrics,
-    toggleAutoCleanupBlankSessions,
-    togglePromptSubmitOnEnter,
-    toggleShowPromptVoiceInput,
-    setDiffViewMode,
-    setToolOutputExpansion,
-    setDiagnosticsExpansion,
-    setThinkingBlocksExpansion,
-    setToolInputsVisibility,
-  } = useConfig()
-
-  const behaviorSettings = createMemo(() =>
-    getBehaviorSettings({
-      preferences,
-      useTauriNativeEventTransport,
-      setUseTauriNativeEventTransport,
-      updatePreferences,
-      toggleShowThinkingBlocks,
-      toggleKeyboardShortcutHints,
-      toggleShowMessageTimeline,
-      toggleShowTimelineTools,
-      toggleUsageMetrics,
-      toggleAutoCleanupBlankSessions,
-      togglePromptSubmitOnEnter,
-      toggleShowPromptVoiceInput,
-      setDiffViewMode,
-      setToolOutputExpansion,
-      setDiagnosticsExpansion,
-      setThinkingBlocksExpansion,
-      setToolInputsVisibility,
-    }).filter(
-      (setting) => setting.id !== "behavior.thinkingBlocksDefault" && setting.id !== "behavior.toolOutputsDefault",
-    ),
-  )
-
-  const [overrides, setOverrides] = createSignal<Map<string, unknown>>(new Map())
-
-  const setOverride = (id: string, value: unknown) => {
-    setOverrides((prev) => {
-      const next = new Map(prev)
-      next.set(id, value)
-      return next
-    })
-  }
-
-  createEffect(() => {
-    const current = overrides()
-    if (current.size === 0) return
-
-    const prefs = preferences()
-    const settings = behaviorSettings()
-
-    let changed = false
-    const next = new Map(current)
-    for (const setting of settings) {
-      if (!next.has(setting.id)) continue
-      const overrideValue = next.get(setting.id)
-      const actualValue = setting.get(prefs)
-      if (Object.is(actualValue, overrideValue)) {
-        next.delete(setting.id)
-        changed = true
-      }
-    }
-
-    if (changed) {
-      setOverrides(next)
-    }
-  })
-
-  const readSettingValue = (setting: BehaviorSetting) => {
-    const current = overrides()
-    if (current.has(setting.id)) return current.get(setting.id)
-    return setting.get(preferences())
-  }
-
-  type SelectOption = { value: string; label: string }
-
-  type ExpansionRow =
-    | { kind: "thinking"; key: "thinking"; label: string }
-    | { kind: "tool"; key: string; label: string }
-
-  const expansionOptions = createMemo<SelectOption[]>(() => [
-    { value: "collapsed", label: t("commands.common.collapsed") },
-    { value: "expanded", label: t("commands.common.expanded") },
-  ])
-
-  const toolExpansionRows = createMemo<ExpansionRow[]>(() => [
-    { kind: "thinking", key: "thinking", label: t("settings.behavior.expansionDefaults.thinking") },
-    ...getConfigurableToolEntries().map((entry) => ({
-      kind: "tool" as const,
-      key: entry.tool,
-      label: entry.labelKey ? t(entry.labelKey) : entry.label,
-    })),
-  ])
-
-  const currentPreset = createMemo(() => preferences().toolCallExpansionDefaults.preset)
-
-  const currentToolMode = (tool: string): ExpansionPreference => {
-    const pref = preferences().toolCallExpansionDefaults
-    const entry = getConfigurableToolEntries().find((item) => item.tool === tool)
-    if (pref.tools[tool]) return pref.tools[tool]
-    if (pref.preset !== "custom" && entry) return entry.expansionPresets[pref.preset]
-    return pref.tools[OTHER_TOOL_NAME] ?? "expanded"
-  }
-
-  const currentThinkingMode = (): ExpansionPreference => {
-    const pref = preferences().toolCallExpansionDefaults
-    if (pref.thinking) return pref.thinking
-    if (pref.preset !== "custom") return THINKING_EXPANSION_PRESETS[pref.preset]
-    return preferences().thinkingBlocksExpansion ?? "expanded"
-  }
-
-  const materializeToolModes = () => {
-    const tools: Record<string, ExpansionPreference> = {}
-    for (const entry of getConfigurableToolEntries()) {
-      tools[entry.tool] = currentToolMode(entry.tool)
-    }
-    return tools
-  }
-
-  const applyExpansionPreset = (preset: ToolCallExpansionPreset) => {
-    const tools = buildToolExpansionPresetDefaults(preset)
-    const thinking = THINKING_EXPANSION_PRESETS[preset]
-    updatePreferences({
-      toolCallExpansionDefaults: { preset, thinking, tools },
-      thinkingBlocksExpansion: thinking,
-      toolOutputExpansion: tools[OTHER_TOOL_NAME] ?? "expanded",
-    })
-  }
-
-  const setExpansionRowMode = (row: ExpansionRow, mode: ExpansionPreference) => {
-    const tools = materializeToolModes()
-    const thinking = row.kind === "thinking" ? mode : currentThinkingMode()
-    if (row.kind === "tool") {
-      tools[row.key] = mode
-    }
-    updatePreferences({
-      toolCallExpansionDefaults: { preset: "custom", thinking, tools },
-      thinkingBlocksExpansion: thinking,
-      toolOutputExpansion: tools[OTHER_TOOL_NAME] ?? preferences().toolOutputExpansion,
-    })
-  }
-
-  const rowMode = (row: ExpansionRow): ExpansionPreference =>
-    row.kind === "thinking" ? currentThinkingMode() : currentToolMode(row.key)
-
-  const selectedExpansionOption = (mode: ExpansionPreference) =>
-    expansionOptions().find((opt) => opt.value === mode)
-
-  const BehaviorRow: Component<{ setting: BehaviorSetting }> = (props) => {
-    const setting = props.setting
-    const disabled = createMemo(() => (setting.disabled ? Boolean(setting.disabled()) : false))
-
-    if (setting.kind === "toggle") {
-      const options = createMemo<SelectOption[]>(() => [
-        { value: "true", label: t("settings.common.enabled") },
-        { value: "false", label: t("settings.common.disabled") },
-      ])
-      const currentValue = createMemo(() => String(Boolean(readSettingValue(setting))))
-      const selectedOption = createMemo(() => options().find((opt) => opt.value === currentValue()))
-
-      return (
-        <div class={`settings-toggle-row ${disabled() ? "opacity-60" : ""}`}>
-          <div>
-            <div class="settings-toggle-title">{t(setting.titleKey)}</div>
-            <div class="settings-toggle-caption">{t(setting.subtitleKey)}</div>
-          </div>
-          <Select<SelectOption>
-            value={selectedOption()}
-            onChange={(opt) => {
-              if (!opt) return
-              const next = opt.value === "true"
-              setOverride(setting.id, next)
-              setting.set(next)
-            }}
-            options={options()}
-            optionValue="value"
-            optionTextValue="label"
-            disabled={disabled()}
-            itemComponent={(itemProps) => (
-              <Select.Item item={itemProps.item} class="selector-option">
-                <Select.ItemLabel class="selector-option-label">{itemProps.item.rawValue.label}</Select.ItemLabel>
-              </Select.Item>
-            )}
-          >
-            <Select.Trigger class="selector-trigger" aria-label={t(setting.titleKey)}>
-              <div class="flex-1 min-w-0">
-                <Select.Value<SelectOption>>
-                  {(state) => (
-                    <span class="selector-trigger-primary selector-trigger-primary--align-left">
-                      {state.selectedOption()?.label}
-                    </span>
-                  )}
-                </Select.Value>
-              </div>
-              <Select.Icon class="selector-trigger-icon">
-                <ChevronDown class="w-3 h-3" />
-              </Select.Icon>
-            </Select.Trigger>
-
-            <Select.Portal>
-              <Select.Content class="selector-popover">
-                <Select.Listbox class="selector-listbox" />
-              </Select.Content>
-            </Select.Portal>
-          </Select>
-        </div>
-      )
-    }
-
-    const enumSetting = setting as Extract<BehaviorSetting, { kind: "enum" }>
-    const options = createMemo<SelectOption[]>(() =>
-      enumSetting.options.map((opt: { value: string; labelKey: string }) => ({
-        value: String(opt.value),
-        label: t(opt.labelKey),
-      })),
-    )
-    const currentValue = createMemo(() => String(readSettingValue(setting) ?? ""))
-    const selectedOption = createMemo(() => options().find((opt) => opt.value === currentValue()))
-
-    return (
-      <div class={`settings-toggle-row ${disabled() ? "opacity-60" : ""}`}>
-        <div>
-          <div class="settings-toggle-title">{t(setting.titleKey)}</div>
-          <div class="settings-toggle-caption">{t(setting.subtitleKey)}</div>
-        </div>
-        <Select<SelectOption>
-          value={selectedOption()}
-          onChange={(opt) => {
-            if (!opt) return
-            setOverride(setting.id, opt.value)
-            enumSetting.set(opt.value as any)
-          }}
-          options={options()}
-          optionValue="value"
-          optionTextValue="label"
-          disabled={disabled()}
-          itemComponent={(itemProps) => (
-            <Select.Item item={itemProps.item} class="selector-option">
-              <Select.ItemLabel class="selector-option-label">{itemProps.item.rawValue.label}</Select.ItemLabel>
-            </Select.Item>
-          )}
-        >
-          <Select.Trigger class="selector-trigger" aria-label={t(setting.titleKey)}>
-            <div class="flex-1 min-w-0">
-              <Select.Value<SelectOption>>
-                {(state) => (
-                  <span class="selector-trigger-primary selector-trigger-primary--align-left">
-                    {state.selectedOption()?.label}
-                  </span>
-                )}
-              </Select.Value>
-            </div>
-            <Select.Icon class="selector-trigger-icon">
-              <ChevronDown class="w-3 h-3" />
-            </Select.Icon>
-          </Select.Trigger>
-
-          <Select.Portal>
-            <Select.Content class="selector-popover">
-              <Select.Listbox class="selector-listbox" />
-            </Select.Content>
-          </Select.Portal>
-        </Select>
-      </div>
-    )
-  }
-
-  const modeLabel = (mode: ThemeMode) => {
-    if (mode === "system") return t("theme.mode.system")
-    if (mode === "light") return t("theme.mode.light")
-    return t("theme.mode.dark")
-  }
-
-  const presetLabel = (preset: ToolCallExpansionPreset | "custom") => t(`settings.behavior.expansionPreset.${preset}.title`)
-
-  return (
-    <div class="settings-section-stack">
-      <div class="settings-card">
-        <div class="settings-card-header">
-          <div>
-            <h3 class="settings-card-title">{t("settings.appearance.theme.title")}</h3>
-            <p class="settings-card-subtitle">{t("settings.appearance.theme.subtitle")}</p>
-          </div>
-          <span class="settings-scope-badge">{t("settings.scope.device")}</span>
-        </div>
-        <div class="settings-choice-grid">
-          {themeModeOptions.map((option) => {
-            const Icon = option.icon
-            return (
-              <button
-                type="button"
-                class="settings-choice"
-                data-selected={themeMode() === option.value ? "true" : "false"}
-                onClick={() => setThemeMode(option.value)}
-              >
-                <span class="settings-choice-icon-wrap">
-                  <Icon class="settings-choice-icon" />
-                </span>
-                <span class="settings-choice-copy">
-                  <span class="settings-choice-label">{modeLabel(option.value)}</span>
-                  <span class="settings-choice-description">{t(`settings.appearance.theme.option.${option.value}`)}</span>
-                </span>
-                <span class="settings-choice-check" aria-hidden="true">
-                  <Check class="w-4 h-4" />
-                </span>
-              </button>
-            )
-          })}
-        </div>
-      </div>
-
-      <div class="settings-card">
-        <div class="settings-card-header">
-          <div>
-            <h3 class="settings-card-title">{t("settings.appearance.behavior.title")}</h3>
-            <p class="settings-card-subtitle">{t("settings.appearance.behavior.subtitle")}</p>
-          </div>
-          <span class="settings-scope-badge">{presetLabel(currentPreset())}</span>
-        </div>
-
-        <div class="settings-expansion-presets" aria-label={t("settings.behavior.expansionPresets.ariaLabel")}>
-          <For each={toolExpansionPresetOptions}>
-            {(preset) => (
-              <button
-                type="button"
-                class="settings-expansion-preset"
-                data-selected={currentPreset() === preset ? "true" : "false"}
-                onClick={() => applyExpansionPreset(preset)}
-              >
-                <span class="settings-expansion-preset-title">{presetLabel(preset)}</span>
-                <span class="settings-expansion-preset-copy">{t(`settings.behavior.expansionPreset.${preset}.description`)}</span>
-              </button>
-            )}
-          </For>
-        </div>
-
-        <div class="settings-expansion-table" role="table" aria-label={t("settings.behavior.expansionDefaults.title")}>
-          <div class="settings-expansion-table-header" role="row">
-            <span role="columnheader">{t("settings.behavior.expansionDefaults.itemColumn")}</span>
-            <span role="columnheader">{t("settings.behavior.expansionDefaults.stateColumn")}</span>
-          </div>
-          <For each={toolExpansionRows()}>
-            {(row) => {
-              const selected = createMemo(() => selectedExpansionOption(rowMode(row)))
-              return (
-                <div class="settings-expansion-row" role="row">
-                  <div class="settings-expansion-row-label" role="cell">
-                    <code>{row.label}</code>
-                  </div>
-                  <div class="settings-expansion-row-control" role="cell">
-                    <Select<SelectOption>
-                      value={selected()}
-                      onChange={(opt) => {
-                        if (!opt) return
-                        setExpansionRowMode(row, opt.value as ExpansionPreference)
-                      }}
-                      options={expansionOptions()}
-                      optionValue="value"
-                      optionTextValue="label"
-                      itemComponent={(itemProps) => (
-                        <Select.Item item={itemProps.item} class="selector-option">
-                          <Select.ItemLabel class="selector-option-label">{itemProps.item.rawValue.label}</Select.ItemLabel>
-                        </Select.Item>
-                      )}
-                    >
-                      <Select.Trigger class="selector-trigger settings-expansion-select" aria-label={t("settings.behavior.expansionDefaults.rowAriaLabel", { item: row.label })}>
-                        <div class="flex-1 min-w-0">
-                          <Select.Value<SelectOption>>
-                            {(state) => (
-                              <span class="selector-trigger-primary selector-trigger-primary--align-left">
-                                {state.selectedOption()?.label}
-                              </span>
-                            )}
-                          </Select.Value>
-                        </div>
-                        <Select.Icon class="selector-trigger-icon">
-                          <ChevronDown class="w-3 h-3" />
-                        </Select.Icon>
-                      </Select.Trigger>
-
-                      <Select.Portal>
-                        <Select.Content class="selector-popover">
-                          <Select.Listbox class="selector-listbox" />
-                        </Select.Content>
-                      </Select.Portal>
-                    </Select>
-                  </div>
-                </div>
-              )
-            }}
-          </For>
-        </div>
-
-        <div class="settings-stack">
-          <For each={behaviorSettings()}>{(setting) => <BehaviorRow setting={setting} />}</For>
-        </div>
-      </div>
-    </div>
-  )
-}
diff --git a/packages/ui/src/components/settings/behavior-setting-rows.tsx b/packages/ui/src/components/settings/behavior-setting-rows.tsx
new file mode 100644
index 00000000..bc576206
--- /dev/null
+++ b/packages/ui/src/components/settings/behavior-setting-rows.tsx
@@ -0,0 +1,153 @@
+import { Select } from "@kobalte/core/select"
+import { ChevronDown } from "lucide-solid"
+import { createEffect, createMemo, createSignal, For, type Accessor, type Component } from "solid-js"
+import { useI18n } from "../../lib/i18n"
+import type { BehaviorSetting } from "../../lib/settings/behavior-registry"
+import type { Preferences } from "../../stores/preferences"
+
+type SelectOption = { value: string; label: string }
+
+interface BehaviorSettingRowsProps {
+  settings: Accessor<BehaviorSetting[]>
+  preferences: Accessor<Preferences>
+}
+
+export const BehaviorSettingRows: Component<BehaviorSettingRowsProps> = (props) => {
+  const { t } = useI18n()
+  const [overrides, setOverrides] = createSignal<Map<string, unknown>>(new Map())
+
+  const setOverride = (id: string, value: unknown) => {
+    setOverrides((previous) => {
+      const next = new Map(previous)
+      next.set(id, value)
+      return next
+    })
+  }
+
+  createEffect(() => {
+    const current = overrides()
+    if (current.size === 0) return
+
+    let changed = false
+    const next = new Map(current)
+    for (const setting of props.settings()) {
+      if (!next.has(setting.id)) continue
+      if (Object.is(setting.get(props.preferences()), next.get(setting.id))) {
+        next.delete(setting.id)
+        changed = true
+      }
+    }
+
+    if (changed) setOverrides(next)
+  })
+
+  const readValue = (setting: BehaviorSetting) => {
+    const current = overrides()
+    return current.has(setting.id) ? current.get(setting.id) : setting.get(props.preferences())
+  }
+
+  const BehaviorRow: Component<{ setting: BehaviorSetting }> = (rowProps) => {
+    const setting = rowProps.setting
+    const disabled = createMemo(() => Boolean(setting.disabled?.()))
+
+    if (setting.kind === "toggle") {
+      const options = createMemo<SelectOption[]>(() => [
+        { value: "true", label: t("settings.common.enabled") },
+        { value: "false", label: t("settings.common.disabled") },
+      ])
+      const selectedOption = createMemo(() => options().find((option) => option.value === String(Boolean(readValue(setting)))))
+
+      return (
+        <div class={`settings-toggle-row ${disabled() ? "opacity-60" : ""}`}>
+          <div>
+            <div class="settings-toggle-title">{t(setting.titleKey)}</div>
+            <div class="settings-toggle-caption">{t(setting.subtitleKey)}</div>
+          </div>
+          <Select<SelectOption>
+            value={selectedOption()}
+            onChange={(option) => {
+              if (!option) return
+              const next = option.value === "true"
+              setOverride(setting.id, next)
+              setting.set(next)
+            }}
+            options={options()}
+            optionValue="value"
+            optionTextValue="label"
+            disabled={disabled()}
+            itemComponent={(itemProps) => (
+              <Select.Item item={itemProps.item} class="selector-option">
+                <Select.ItemLabel class="selector-option-label">{itemProps.item.rawValue.label}</Select.ItemLabel>
+              </Select.Item>
+            )}
+          >
+            <Select.Trigger class="selector-trigger" aria-label={t(setting.titleKey)}>
+              <div class="flex-1 min-w-0">
+                <Select.Value<SelectOption>>
+                  {(state) => <span class="selector-trigger-primary selector-trigger-primary--align-left">{state.selectedOption()?.label}</span>}
+                </Select.Value>
+              </div>
+              <Select.Icon class="selector-trigger-icon">
+                <ChevronDown class="w-3 h-3" />
+              </Select.Icon>
+            </Select.Trigger>
+            <Select.Portal>
+              <Select.Content class="selector-popover">
+                <Select.Listbox class="selector-listbox" />
+              </Select.Content>
+            </Select.Portal>
+          </Select>
+        </div>
+      )
+    }
+
+    const options = createMemo<SelectOption[]>(() =>
+      setting.options.map((option) => ({ value: String(option.value), label: t(option.labelKey) })),
+    )
+    const selectedOption = createMemo(() => options().find((option) => option.value === String(readValue(setting) ?? "")))
+
+    return (
+      <div class={`settings-toggle-row ${disabled() ? "opacity-60" : ""}`}>
+        <div>
+          <div class="settings-toggle-title">{t(setting.titleKey)}</div>
+          <div class="settings-toggle-caption">{t(setting.subtitleKey)}</div>
+        </div>
+        <Select<SelectOption>
+          value={selectedOption()}
+          onChange={(option) => {
+            if (!option) return
+            setOverride(setting.id, option.value)
+            setting.set(option.value)
+          }}
+          options={options()}
+          optionValue="value"
+          optionTextValue="label"
+          disabled={disabled()}
+          itemComponent={(itemProps) => (
+            <Select.Item item={itemProps.item} class="selector-option">
+              <Select.ItemLabel class="selector-option-label">{itemProps.item.rawValue.label}</Select.ItemLabel>
+            </Select.Item>
+          )}
+        >
+          <Select.Trigger class="selector-trigger" aria-label={t(setting.titleKey)}>
+            <div class="flex-1 min-w-0">
+              <Select.Value<SelectOption>>
+                {(state) => <span class="selector-trigger-primary selector-trigger-primary--align-left">{state.selectedOption()?.label}</span>}
+              </Select.Value>
+            </div>
+            <Select.Icon class="selector-trigger-icon">
+              <ChevronDown class="w-3 h-3" />
+            </Select.Icon>
+          </Select.Trigger>
+          <Select.Portal>
+            <Select.Content class="selector-popover">
+              <Select.Listbox class="selector-listbox" />
+            </Select.Content>
+          </Select.Portal>
+        </Select>
+      </div>
+    )
+  }
+
+  return <For each={props.settings()}>{(setting) => <BehaviorRow setting={setting} />}</For>
+}
diff --git a/packages/ui/src/components/settings/chat-settings-section.tsx b/packages/ui/src/components/settings/chat-settings-section.tsx
new file mode 100644
index 00000000..595448b7
--- /dev/null
+++ b/packages/ui/src/components/settings/chat-settings-section.tsx
@@ -0,0 +1,270 @@
+import { Select } from "@kobalte/core/select"
+import { createMemo, For, type Component } from "solid-js"
+import { ChevronDown } from "lucide-solid"
+import { useI18n } from "../../lib/i18n"
+import {
+  useConfig,
+  type Preferences,
+  type ToolCallExpansionPreset,
+  type VisibilityPreference,
+} from "../../stores/preferences"
+import {
+  buildToolExpansionPresetDefaults,
+  getConfigurableToolEntries,
+  OTHER_TOOL_NAME,
+  THINKING_EXPANSION_PRESETS,
+} from "../tool-call/tool-registry"
+
+const toolExpansionPresetOptions: ToolCallExpansionPreset[] = ["minimal", "balanced", "detailed", "everything"]
+
+const transcriptDetailPresets = {
+  minimal: {
+    showThinkingBlocks: false,
+    diagnosticsExpansion: "collapsed",
+    toolInputsVisibility: "hidden",
+    showUsageMetrics: false,
+    usageMetricsExpansion: "collapsed",
+  },
+  balanced: {
+    showThinkingBlocks: false,
+    diagnosticsExpansion: "expanded",
+    toolInputsVisibility: "collapsed",
+    showUsageMetrics: true,
+    usageMetricsExpansion: "collapsed",
+  },
+  detailed: {
+    showThinkingBlocks: true,
+    diagnosticsExpansion: "expanded",
+    toolInputsVisibility: "collapsed",
+    showUsageMetrics: true,
+    usageMetricsExpansion: "expanded",
+  },
+  everything: {
+    showThinkingBlocks: true,
+    diagnosticsExpansion: "expanded",
+    toolInputsVisibility: "expanded",
+    showUsageMetrics: true,
+    usageMetricsExpansion: "expanded",
+  },
+} as const satisfies Record<
+  ToolCallExpansionPreset,
+  Pick<
+    Preferences,
+    | "showThinkingBlocks"
+    | "diagnosticsExpansion"
+    | "toolInputsVisibility"
+    | "showUsageMetrics"
+    | "usageMetricsExpansion"
+  >
+>
+
+type SelectOption = { value: VisibilityPreference; label: string }
+
+type VisibilityRow =
+  | { kind: "thinking"; key: "thinking"; label: string }
+  | { kind: "tool"; key: string; label: string }
+  | { kind: "diagnostics"; key: "diagnostics"; label: string }
+  | { kind: "inputs"; key: "inputs"; label: string }
+  | { kind: "usage"; key: "usage"; label: string }
+
+export const ChatSettingsSection: Component = () => {
+  const { t } = useI18n()
+  const { preferences, updatePreferences } = useConfig()
+
+  const visibilityOptions = createMemo<SelectOption[]>(() => [
+    { value: "hidden", label: t("commands.common.hidden") },
+    { value: "collapsed", label: t("commands.common.collapsed") },
+    { value: "expanded", label: t("commands.common.expanded") },
+  ])
+
+  const visibilityRows = createMemo<VisibilityRow[]>(() => [
+    { kind: "thinking", key: "thinking", label: t("settings.behavior.expansionDefaults.thinking") },
+    ...getConfigurableToolEntries().map((entry) => ({
+      kind: "tool" as const,
+      key: entry.tool,
+      label: entry.labelKey ? t(entry.labelKey) : entry.label,
+    })),
+    { kind: "diagnostics", key: "diagnostics", label: t("settings.behavior.diagnosticsDefault.title") },
+    { kind: "inputs", key: "inputs", label: t("settings.behavior.toolInputsVisibility.title") },
+    { kind: "usage", key: "usage", label: t("settings.behavior.usageMetrics.title") },
+  ])
+
+  const currentToolMode = (tool: string): VisibilityPreference => {
+    const pref = preferences().toolCallExpansionDefaults
+    const entry = getConfigurableToolEntries().find((item) => item.tool === tool)
+    if (pref.tools[tool]) return pref.tools[tool]
+    if (pref.preset !== "custom" && entry) return entry.expansionPresets[pref.preset]
+    return pref.tools[OTHER_TOOL_NAME] ?? "expanded"
+  }
+
+  const currentThinkingExpansion = () => {
+    const current = preferences()
+    const pref = current.toolCallExpansionDefaults
+    if (pref.thinking) return pref.thinking
+    if (pref.preset !== "custom") return THINKING_EXPANSION_PRESETS[pref.preset]
+    return current.thinkingBlocksExpansion ?? "expanded"
+  }
+
+  const currentThinkingMode = (): VisibilityPreference =>
+    preferences().showThinkingBlocks ? currentThinkingExpansion() : "hidden"
+
+  const currentUsageMode = (): VisibilityPreference => {
+    const current = preferences()
+    return current.showUsageMetrics ? current.usageMetricsExpansion : "hidden"
+  }
+
+  const currentPreset = createMemo(() => {
+    const current = preferences()
+    const preset = current.toolCallExpansionDefaults.preset
+    if (preset === "custom") return preset
+    const detail = transcriptDetailPresets[preset]
+    const expectedThinking = detail.showThinkingBlocks ? THINKING_EXPANSION_PRESETS[preset] : "hidden"
+    return currentThinkingMode() === expectedThinking &&
+      current.diagnosticsExpansion === detail.diagnosticsExpansion &&
+      current.toolInputsVisibility === detail.toolInputsVisibility &&
+      current.showUsageMetrics === detail.showUsageMetrics &&
+      current.usageMetricsExpansion === detail.usageMetricsExpansion
+      ? preset
+      : "custom"
+  })
+
+  const materializeToolModes = () => {
+    const tools: Record<string, VisibilityPreference> = {}
+    for (const entry of getConfigurableToolEntries()) tools[entry.tool] = currentToolMode(entry.tool)
+    return tools
+  }
+
+  const applyExpansionPreset = (preset: ToolCallExpansionPreset) => {
+    const tools = buildToolExpansionPresetDefaults(preset)
+    const thinking = THINKING_EXPANSION_PRESETS[preset]
+    updatePreferences({
+      ...transcriptDetailPresets[preset],
+      toolCallExpansionDefaults: { preset, thinking, tools },
+      thinkingBlocksExpansion: thinking,
+      toolOutputExpansion: tools[OTHER_TOOL_NAME] === "expanded" ? "expanded" : "collapsed",
+    })
+  }
+
+  const setVisibilityRowMode = (row: VisibilityRow, mode: VisibilityPreference) => {
+    const current = preferences()
+    if (row.kind === "diagnostics") {
+      updatePreferences({ diagnosticsExpansion: mode })
+      return
+    }
+    if (row.kind === "inputs") {
+      updatePreferences({ toolInputsVisibility: mode })
+      return
+    }
+    if (row.kind === "usage") {
+      updatePreferences({
+        showUsageMetrics: mode !== "hidden",
+        usageMetricsExpansion: mode === "hidden" ? current.usageMetricsExpansion : mode,
+      })
+      return
+    }
+
+    const tools = materializeToolModes()
+    const thinking = row.kind === "thinking" && mode !== "hidden" ? mode : currentThinkingExpansion()
+    if (row.kind === "tool") tools[row.key] = mode
+    updatePreferences({
+      showThinkingBlocks: row.kind === "thinking" ? mode !== "hidden" : current.showThinkingBlocks,
+      toolCallExpansionDefaults: { preset: "custom", thinking, tools },
+      thinkingBlocksExpansion:
+        row.kind === "thinking" && mode !== "hidden" ? mode : current.thinkingBlocksExpansion,
+      toolOutputExpansion:
+        row.kind === "tool" && row.key === OTHER_TOOL_NAME && mode !== "hidden"
+          ? mode
+          : current.toolOutputExpansion,
+    })
+  }
+
+  const rowMode = (row: VisibilityRow): VisibilityPreference => {
+    if (row.kind === "thinking") return currentThinkingMode()
+    if (row.kind === "tool") return currentToolMode(row.key)
+    if (row.kind === "diagnostics") return preferences().diagnosticsExpansion
+    if (row.kind === "inputs") return preferences().toolInputsVisibility
+    return currentUsageMode()
+  }
+
+  const selectedVisibilityOption = (mode: VisibilityPreference) =>
+    visibilityOptions().find((option) => option.value === mode)
+
+  const presetLabel = (preset: ToolCallExpansionPreset | "custom") =>
+    t(`settings.behavior.expansionPreset.${preset}.title`)
+
+  return (
+    <div class="settings-section-stack">
+      <section class="settings-card">
+        <div class="settings-card-header">
+          <div>
+            <h3 class="settings-card-title">{t("settings.behavior.expansionPresets.ariaLabel")}</h3>
+            <p class="settings-card-subtitle">{t("settings.appearance.behavior.subtitle")}</p>
+          </div>
+          <span class="settings-scope-badge">{presetLabel(currentPreset())}</span>
+        </div>
+
+        <div class="settings-expansion-presets" aria-label={t("settings.behavior.expansionPresets.ariaLabel")}>
+          <For each={toolExpansionPresetOptions}>
+            {(preset) => (
+              <button
+                type="button"
+                class="settings-expansion-preset"
+                data-selected={currentPreset() === preset ? "true" : "false"}
+                onClick={() => applyExpansionPreset(preset)}
+              >
+                <span class="settings-expansion-preset-title">{presetLabel(preset)}</span>
+                <span class="settings-expansion-preset-copy">{t(`settings.behavior.expansionPreset.${preset}.description`)}</span>
+              </button>
+            )}
+          </For>
+        </div>
+
+        <div class="settings-expansion-table" role="table" aria-label={t("settings.behavior.expansionDefaults.title")}>
+          <div class="settings-expansion-table-header" role="row">
+            <span role="columnheader">{t("settings.behavior.expansionDefaults.itemColumn")}</span>
+            <span role="columnheader">{t("settings.behavior.expansionDefaults.stateColumn")}</span>
+          </div>
+          <For each={visibilityRows()}>
+            {(row) => {
+              const selected = createMemo(() => selectedVisibilityOption(rowMode(row)))
+              return (
+                <div class="settings-expansion-row" role="row">
+                  <div class="settings-expansion-row-label" role="cell"><code>{row.label}</code></div>
+                  <div class="settings-expansion-row-control" role="cell">
+                    <Select<SelectOption>
+                      value={selected()}
+                      onChange={(option) => option && setVisibilityRowMode(row, option.value)}
+                      options={visibilityOptions()}
+                      optionValue="value"
+                      optionTextValue="label"
+                      itemComponent={(itemProps) => (
+                        <Select.Item item={itemProps.item} class="selector-option">
+                          <Select.ItemLabel class="selector-option-label">{itemProps.item.rawValue.label}</Select.ItemLabel>
+                        </Select.Item>
+                      )}
+                    >
+                      <Select.Trigger
+                        class="selector-trigger settings-expansion-select"
+                        aria-label={t("settings.behavior.expansionDefaults.rowAriaLabel", { item: row.label })}
+                      >
+                        <div class="flex-1 min-w-0">
+                          <Select.Value<SelectOption>>
+                            {(state) => <span class="selector-trigger-primary selector-trigger-primary--align-left">{state.selectedOption()?.label}</span>}
+                          </Select.Value>
+                        </div>
+                        <Select.Icon class="selector-trigger-icon"><ChevronDown class="w-3 h-3" /></Select.Icon>
+                      </Select.Trigger>
+                      <Select.Portal>
+                        <Select.Content class="selector-popover"><Select.Listbox class="selector-listbox" /></Select.Content>
+                      </Select.Portal>
+                    </Select>
+                  </div>
+                </div>
+              )
+            }}
+          </For>
+        </div>
+      </section>
+    </div>
+  )
+}
diff --git a/packages/ui/src/components/settings/config-files-settings-section.tsx b/packages/ui/src/components/settings/config-files-settings-section.tsx
index e1f3f986..9c08312e 100644
--- a/packages/ui/src/components/settings/config-files-settings-section.tsx
+++ b/packages/ui/src/components/settings/config-files-settings-section.tsx
@@ -122,6 +122,7 @@ export const ConfigFilesSettingsSection: Component = () => {
 
   return (
     <div class="settings-section-stack config-files-section">
+      <h2 class="sr-only">{t("settings.configFiles.title")}</h2>
       <div class="config-files-card">
         <div class="config-files-toolbar">
           <div class="config-files-selector-field">
diff --git a/packages/ui/src/components/settings/general-settings-section.tsx b/packages/ui/src/components/settings/general-settings-section.tsx
new file mode 100644
index 00000000..f55502c0
--- /dev/null
+++ b/packages/ui/src/components/settings/general-settings-section.tsx
@@ -0,0 +1,94 @@
+import { Check, Laptop, Moon, Sun } from "lucide-solid"
+import { createMemo, type Component } from "solid-js"
+import { useI18n } from "../../lib/i18n"
+import { getBehaviorSettings, type BehaviorSetting } from "../../lib/settings/behavior-registry"
+import { useTheme, type ThemeMode } from "../../lib/theme"
+import { useConfig } from "../../stores/preferences"
+import { LocaleSelector } from "../locale-selector"
+import { BehaviorSettingRows } from "./behavior-setting-rows"
+import { StartupStateSettingsCard } from "./startup-state-settings-card"
+
+const themeModeOptions: Array<{ value: ThemeMode; icon: typeof Laptop }> = [
+  { value: "system", icon: Laptop },
+  { value: "light", icon: Sun },
+  { value: "dark", icon: Moon },
+]
+
+export const GeneralSettingsSection: Component = () => {
+  const { t } = useI18n()
+  const { themeMode, setThemeMode } = useTheme()
+  const config = useConfig()
+  const { updatePreferences } = config
+  const generalSettings = createMemo<BehaviorSetting[]>(() => [
+    ...getBehaviorSettings(config).filter(
+      (setting) =>
+        setting.id === "behavior.keyboardShortcutHints" ||
+        setting.id === "behavior.messageTimeline" ||
+        setting.id === "behavior.timelineToolCalls" ||
+        setting.id === "behavior.diffViewMode" ||
+        setting.id === "behavior.promptSubmitOnEnter",
+    ),
+    {
+      kind: "toggle",
+      id: "behavior.holdLongAssistantReplies",
+      titleKey: "settings.behavior.holdLongAssistantReplies.title",
+      subtitleKey: "settings.behavior.holdLongAssistantReplies.subtitle",
+      get: (current) => Boolean(current.holdLongAssistantReplies ?? true),
+      set: (next) => updatePreferences({ holdLongAssistantReplies: next }),
+    },
+  ])
+
+  const modeLabel = (mode: ThemeMode) => {
+    if (mode === "system") return t("theme.mode.system")
+    if (mode === "light") return t("theme.mode.light")
+    return t("theme.mode.dark")
+  }
+
+  return (
+    <div class="settings-section-stack">
+      <div class="settings-card">
+        <div class="settings-card-header">
+          <div>
+            <h3 class="settings-card-title">{t("settings.appearance.theme.title")}</h3>
+            <p class="settings-card-subtitle">{t("settings.appearance.theme.subtitle")}</p>
+          </div>
+          <span class="settings-scope-badge">{t("settings.scope.device")}</span>
+        </div>
+        <div class="settings-choice-grid">
+          {themeModeOptions.map((option) => {
+            const Icon = option.icon
+            return (
+              <button type="button" class="settings-choice" data-selected={themeMode() === option.value ? "true" : "false"} onClick={() => setThemeMode(option.value)}>
+                <span class="settings-choice-icon-wrap"><Icon class="settings-choice-icon" /></span>
+                <span class="settings-choice-copy">
+                  <span class="settings-choice-label">{modeLabel(option.value)}</span>
+                  <span class="settings-choice-description">{t(`settings.appearance.theme.option.${option.value}`)}</span>
+                </span>
+                <span class="settings-choice-check" aria-hidden="true"><Check class="w-4 h-4" /></span>
+              </button>
+            )
+          })}
+        </div>
+      </div>
+
+      <div class="settings-card">
+        <div class="settings-card-header">
+          <div>
+            <h3 class="settings-card-title">{t("folderSelection.language.ariaLabel")}</h3>
+            <p class="settings-card-subtitle">{t("settings.general.language.subtitle")}</p>
+          </div>
+          <span class="settings-scope-badge">{t("settings.scope.device")}</span>
+        </div>
+        <LocaleSelector />
+      </div>
+
+      <StartupStateSettingsCard />
+
+      <div class="settings-card">
+        <div class="settings-stack">
+          <BehaviorSettingRows settings={generalSettings} preferences={config.preferences} />
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/packages/ui/src/components/settings/opencode-settings-section.tsx b/packages/ui/src/components/settings/opencode-settings-section.tsx
index 8c0bc01b..f919dbf0 100644
--- a/packages/ui/src/components/settings/opencode-settings-section.tsx
+++ b/packages/ui/src/components/settings/opencode-settings-section.tsx
@@ -2,15 +2,11 @@ import { Select } from "@kobalte/core/select"
 import { createEffect, createMemo, createSignal, type Component } from "solid-js"
 import { ChevronDown, Terminal } from "lucide-solid"
 import OpenCodeBinarySelector from "../opencode-binary-selector"
-import EnvironmentVariablesEditor from "../environment-variables-editor"
-import { useConfig } from "../../stores/preferences"
-import type { ServerLogLevel } from "../../stores/preferences"
+import { useConfig, type ServerLogLevel } from "../../stores/preferences"
 import { useI18n } from "../../lib/i18n"
+import { OpenCodeUpdateCard } from "./opencode-update-card"
 
-type LogLevelOption = {
-  value: ServerLogLevel
-  label: string
-}
+type LogLevelOption = { value: ServerLogLevel; label: string }
 
 export const OpenCodeSettingsSection: Component = () => {
   const { t } = useI18n()
@@ -53,6 +49,8 @@ export const OpenCodeSettingsSection: Component = () => {
         <OpenCodeBinarySelector selectedBinary={selectedBinary()} onBinaryChange={handleBinaryChange} isVisible />
       </div>
 
+      <OpenCodeUpdateCard />
+
       <div class="settings-card">
         <div class="settings-card-header">
           <div>
@@ -69,10 +67,7 @@ export const OpenCodeSettingsSection: Component = () => {
             </div>
             <Select<LogLevelOption>
               value={selectedLogLevel()}
-              onChange={(option) => {
-                if (!option) return
-                updateLogLevel(option.value)
-              }}
+              onChange={(option) => option && updateLogLevel(option.value)}
               options={logLevelOptions()}
               optionValue="value"
               optionTextValue="label"
@@ -85,38 +80,18 @@ export const OpenCodeSettingsSection: Component = () => {
               <Select.Trigger class="selector-trigger" aria-label={t("settings.opencode.logLevel.title")}>
                 <div class="flex-1 min-w-0">
                   <Select.Value<LogLevelOption>>
-                    {(state) => (
-                      <span class="selector-trigger-primary selector-trigger-primary--align-left">
-                        {state.selectedOption()?.label}
-                      </span>
-                    )}
+                    {(state) => <span class="selector-trigger-primary selector-trigger-primary--align-left">{state.selectedOption()?.label}</span>}
                   </Select.Value>
                 </div>
-                <Select.Icon class="selector-trigger-icon">
-                  <ChevronDown class="w-3 h-3" />
-                </Select.Icon>
+                <Select.Icon class="selector-trigger-icon"><ChevronDown class="w-3 h-3" /></Select.Icon>
               </Select.Trigger>
-
               <Select.Portal>
-                <Select.Content class="selector-popover">
-                  <Select.Listbox class="selector-listbox" />
-                </Select.Content>
+                <Select.Content class="selector-popover"><Select.Listbox class="selector-listbox" /></Select.Content>
               </Select.Portal>
             </Select>
           </div>
         </div>
       </div>
-
-      <div class="settings-card">
-        <div class="settings-card-header">
-          <div>
-            <h3 class="settings-card-title">{t("advancedSettings.environmentVariables.title")}</h3>
-            <p class="settings-card-subtitle">{t("advancedSettings.environmentVariables.subtitle")}</p>
-          </div>
-          <span class="settings-scope-badge settings-scope-badge-server">{t("settings.scope.server")}</span>
-        </div>
-        <EnvironmentVariablesEditor />
-      </div>
     </div>
   )
 }
diff --git a/packages/ui/src/components/settings/opencode-update-card.tsx b/packages/ui/src/components/settings/opencode-update-card.tsx
new file mode 100644
index 00000000..841314ee
--- /dev/null
+++ b/packages/ui/src/components/settings/opencode-update-card.tsx
@@ -0,0 +1,123 @@
+import { createEffect, createResource, createSignal, Show, type Component } from "solid-js"
+import { serverApi } from "../../lib/api-client"
+import { useI18n } from "../../lib/i18n"
+import { useConfig } from "../../stores/preferences"
+
+export const OpenCodeUpdateCard: Component = () => {
+  const { t } = useI18n()
+  const { serverSettings } = useConfig()
+  const [status, { mutate, refetch }] = createResource(
+    () => serverSettings().opencodeBinary || "opencode",
+    () => serverApi.fetchOpenCodeUpdateStatus(),
+  )
+  const [updating, setUpdating] = createSignal(false)
+  const [updatedVersion, setUpdatedVersion] = createSignal<string | null>(null)
+  const [updateFailed, setUpdateFailed] = createSignal(false)
+
+  createEffect(() => {
+    serverSettings().opencodeBinary
+    setUpdatedVersion(null)
+    setUpdateFailed(false)
+  })
+
+  const handleUpdate = async () => {
+    if (updating()) return
+    const binary = serverSettings().opencodeBinary || "opencode"
+    setUpdating(true)
+    setUpdateFailed(false)
+    try {
+      const result = await serverApi.updateOpenCode()
+      if ((serverSettings().opencodeBinary || "opencode") !== binary) return
+      setUpdatedVersion(result.version)
+      mutate({
+        currentVersion: result.version,
+        latestVersion: result.version,
+        updateAvailable: false,
+        canUpgrade: false,
+      })
+    } catch {
+      if ((serverSettings().opencodeBinary || "opencode") === binary) setUpdateFailed(true)
+    } finally {
+      setUpdating(false)
+    }
+  }
+
+  return (
+    <div class="settings-card">
+      <div class="settings-card-header">
+        <div>
+          <h3 class="settings-card-title">{t("settings.opencode.update.title")}</h3>
+          <p class="settings-card-subtitle">{t("settings.opencode.update.subtitle")}</p>
+        </div>
+        <span class="settings-scope-badge settings-scope-badge-server">{t("settings.scope.server")}</span>
+      </div>
+
+      <Show when={!status.loading} fallback={<div class="settings-toggle-caption">{t("settings.opencode.update.checking")}</div>}>
+        <Show
+          when={!status.error && status()}
+          fallback={
+            <div>
+              <div class="settings-error-message" role="alert">{t("settings.opencode.update.checkFailed")}</div>
+              <button type="button" class="settings-pill-button" onClick={() => void refetch()}>
+                {t("settings.opencode.update.retry")}
+              </button>
+            </div>
+          }
+        >
+          {(updateStatus) => (
+            <>
+              <div class="settings-info-grid">
+                <div class="settings-info-row">
+                  <span class="settings-info-label">{t("settings.opencode.update.installed")}</span>
+                  <span class="settings-info-value">{updateStatus().currentVersion}</span>
+                </div>
+              </div>
+
+              <Show when={updateStatus().checkError}>
+                <div class="settings-error-message" role="status">{t("settings.opencode.update.checkFailed")}</div>
+                <div class="settings-info-actions">
+                  <button type="button" class="settings-pill-button" onClick={() => void refetch()}>
+                    {t("settings.opencode.update.retry")}
+                  </button>
+                </div>
+              </Show>
+
+              <Show when={!updateStatus().checkError}>
+                <Show when={updateStatus().updateAvailable} fallback={
+                  <div class="settings-toggle-caption" role="status">{t("settings.opencode.update.upToDate")}</div>
+                }>
+                  <div class="settings-info-actions">
+                    <button
+                      type="button"
+                      class="settings-pill-button"
+                      disabled={!updateStatus().canUpgrade || updating()}
+                      onClick={() => void handleUpdate()}
+                    >
+                      {updating()
+                        ? t("settings.opencode.update.updating")
+                        : t("settings.opencode.update.action", { version: updateStatus().latestVersion ?? "" })}
+                    </button>
+                  </div>
+                  <Show when={!updateStatus().canUpgrade}>
+                    <div class="settings-toggle-caption">{t("settings.opencode.update.requiresInstance")}</div>
+                  </Show>
+                </Show>
+              </Show>
+            </>
+          )}
+        </Show>
+      </Show>
+
+      <Show when={updatedVersion()}>
+        {(version) => (
+          <div class="settings-info-toast" role="status" aria-live="polite">
+            {t("settings.opencode.update.success", { version: version() })}
+          </div>
+        )}
+      </Show>
+      <Show when={updateFailed()}>
+        <div class="settings-error-message" role="alert">{t("settings.opencode.update.failed")}</div>
+      </Show>
+    </div>
+  )
+}
diff --git a/packages/ui/src/components/settings/providers-settings-section.tsx b/packages/ui/src/components/settings/providers-settings-section.tsx
new file mode 100644
index 00000000..50988162
--- /dev/null
+++ b/packages/ui/src/components/settings/providers-settings-section.tsx
@@ -0,0 +1,7 @@
+import { type Component } from "solid-js"
+import { activeInstanceId } from "../../stores/instances"
+import { ProviderManagerModal } from "../provider-auth/provider-manager-modal"
+
+export const ProvidersSettingsSection: Component = () => {
+  return <ProviderManagerModal instanceId={activeInstanceId() ?? ""} embedded />
+}
diff --git a/packages/ui/src/components/settings/saved-remote-servers-card.tsx b/packages/ui/src/components/settings/saved-remote-servers-card.tsx
new file mode 100644
index 00000000..139a0a53
--- /dev/null
+++ b/packages/ui/src/components/settings/saved-remote-servers-card.tsx
@@ -0,0 +1,67 @@
+import { Globe, Loader2, Plus, Trash2 } from "lucide-solid"
+import { createSignal, For, Show, type Component } from "solid-js"
+import { useI18n } from "../../lib/i18n"
+import { useRemoteServerProfiles } from "../../lib/hooks/use-remote-server-profiles"
+import { RemoteServerDialog } from "../remote-server-dialog"
+
+export const SavedRemoteServersCard: Component = () => {
+  const { t } = useI18n()
+  const { remoteServers, connectingServerId, saveServer, connectSavedServer, removeRemoteServerProfile } = useRemoteServerProfiles()
+  const [dialogOpen, setDialogOpen] = createSignal(false)
+
+  return (
+    <>
+      <div class="settings-card">
+        <div class="settings-card-header">
+          <div class="settings-card-heading-with-icon">
+            <Globe class="settings-card-heading-icon" />
+            <div>
+              <h3 class="settings-card-title">{t("folderSelection.tabs.servers")}</h3>
+              <p class="settings-card-subtitle">{t("folderSelection.servers.empty.description")}</p>
+            </div>
+          </div>
+          <button type="button" class="selector-button selector-button-secondary" onClick={() => setDialogOpen(true)}>
+            <Plus class="w-4 h-4" />
+            <span>{t("folderSelection.actions.connectButton")}</span>
+          </button>
+        </div>
+        <div class="settings-card-content">
+          <Show when={remoteServers().length > 0} fallback={<div class="settings-card-message">{t("folderSelection.servers.empty.title")}</div>}>
+            <For each={remoteServers()}>
+              {(server) => (
+                <div class="settings-toggle-row settings-toggle-row-compact">
+                  <div class="min-w-0">
+                    <div class="settings-toggle-title truncate">{server.name}</div>
+                    <div class="settings-toggle-caption font-mono truncate">{server.baseUrl}</div>
+                  </div>
+                  <div class="flex items-center gap-2">
+                    <button
+                      type="button"
+                      class="selector-button selector-button-secondary"
+                      disabled={Boolean(connectingServerId())}
+                      aria-label={`${t("folderSelection.servers.dialog.connect")}: ${server.name}`}
+                      title={`${t("folderSelection.servers.dialog.connect")}: ${server.name}`}
+                      onClick={() => void connectSavedServer(server.id)}
+                    >
+                      <Show when={connectingServerId() === server.id} fallback={<Globe class="w-4 h-4" />}><Loader2 class="w-4 h-4 animate-spin" /></Show>
+                    </button>
+                    <button
+                      type="button"
+                      class="selector-button selector-button-secondary"
+                      title={`${t("folderSelection.servers.remove")}: ${server.name}`}
+                      aria-label={`${t("folderSelection.servers.remove")}: ${server.name}`}
+                      onClick={() => removeRemoteServerProfile(server.id)}
+                    >
+                      <Trash2 class="w-4 h-4" />
+                    </button>
+                  </div>
+                </div>
+              )}
+            </For>
+          </Show>
+        </div>
+      </div>
+      <RemoteServerDialog open={dialogOpen()} onOpenChange={setDialogOpen} onSubmit={saveServer} />
+    </>
+  )
+}
diff --git a/packages/ui/src/components/settings/speech-settings-card.tsx b/packages/ui/src/components/settings/speech-settings-card.tsx
index 6a196315..66205368 100644
--- a/packages/ui/src/components/settings/speech-settings-card.tsx
+++ b/packages/ui/src/components/settings/speech-settings-card.tsx
@@ -2,14 +2,23 @@ import { For, Show, createEffect, createMemo, createSignal, type Component } fro
 import { Loader2, Mic, Square, Volume2 } from "lucide-solid"
 import { useConfig, type SpeechSettings } from "../../stores/preferences"
 import { useI18n } from "../../lib/i18n"
-import { loadSpeechCapabilities, speechCapabilities, speechCapabilitiesError, speechCapabilitiesLoading } from "../../stores/speech"
+import { loadSpeechCapabilities, serverSupportsSeparateProviders, speechCapabilities, speechCapabilitiesError, speechCapabilitiesLoading } from "../../stores/speech"
+import { buildDirSave } from "../../lib/speech-dir-save"
 import { getLogger } from "../../lib/logger"
 import { useSpeech } from "../../lib/hooks/use-speech"
+import { useTranscriptionTest } from "../../lib/hooks/use-transcription-test"
 import { getSpeechPlaybackSupport } from "../../lib/speech-playback-support"
 
 const log = getLogger("actions")
 
+type DirectionalDraft = {
+  apiKey: string
+  baseUrl: string
+  model: string
+}
+
 type DraftFields = {
+  separateProviders: boolean
   apiKey: string
   baseUrl: string
   sttModel: string
@@ -17,10 +26,22 @@ type DraftFields = {
   ttsVoice: string
   playbackMode: SpeechSettings["playbackMode"]
   ttsFormat: SpeechSettings["ttsFormat"]
+  stt: DirectionalDraft
+  tts: DirectionalDraft
+}
+
+function createDirectionalDraft(speech: SpeechSettings, direction: "stt" | "tts"): DirectionalDraft {
+  const dir = speech[direction]
+  return {
+    apiKey: "",
+    baseUrl: dir.baseUrl ?? "",
+    model: dir.model,
+  }
 }
 
 function createDraftFields(speech: SpeechSettings): DraftFields {
   return {
+    separateProviders: speech.separateProviders,
     apiKey: "",
     baseUrl: speech.baseUrl ?? "",
     sttModel: speech.sttModel,
@@ -28,18 +49,31 @@ function createDraftFields(speech: SpeechSettings): DraftFields {
     ttsVoice: speech.ttsVoice,
     playbackMode: speech.playbackMode,
     ttsFormat: speech.ttsFormat,
+    stt: createDirectionalDraft(speech, "stt"),
+    tts: createDirectionalDraft(speech, "tts"),
   }
 }
 
+function isDirectionalDraftEqual(a: DirectionalDraft, b: DirectionalDraft): boolean {
+  return (
+    a.apiKey === b.apiKey &&
+    a.baseUrl === b.baseUrl &&
+    a.model === b.model
+  )
+}
+
 function isDraftEqual(a: DraftFields, b: DraftFields): boolean {
   return (
+    a.separateProviders === b.separateProviders &&
     a.apiKey === b.apiKey &&
     a.baseUrl === b.baseUrl &&
     a.sttModel === b.sttModel &&
     a.ttsModel === b.ttsModel &&
     a.ttsVoice === b.ttsVoice &&
     a.playbackMode === b.playbackMode &&
-    a.ttsFormat === b.ttsFormat
+    a.ttsFormat === b.ttsFormat &&
+    isDirectionalDraftEqual(a.stt, b.stt) &&
+    isDirectionalDraftEqual(a.tts, b.tts)
   )
 }
 
@@ -52,6 +86,10 @@ export const SpeechSettingsCard: Component = () => {
   const [drafts, setDrafts] = createSignal<DraftFields>(initialDrafts)
   const [apiKeyTouched, setApiKeyTouched] = createSignal(false)
   const [clearStoredApiKey, setClearStoredApiKey] = createSignal(false)
+  const [sttApiKeyTouched, setSttApiKeyTouched] = createSignal(false)
+  const [clearSttApiKey, setClearSttApiKey] = createSignal(false)
+  const [ttsApiKeyTouched, setTtsApiKeyTouched] = createSignal(false)
+  const [clearTtsApiKey, setClearTtsApiKey] = createSignal(false)
 
   const testSpeech = useSpeech({
     id: () => "settings-speech-test",
@@ -62,19 +100,24 @@ export const SpeechSettingsCard: Component = () => {
     }),
   })
 
+  const testTranscription = useTranscriptionTest()
+
   createEffect(() => {
     const speech = serverSettings().speech
     const nextDrafts = createDraftFields(speech)
     if (!isSaving() && !isDirty()) {
-      if (!isDraftEqual(drafts(), nextDrafts)) {
-        setDrafts(nextDrafts)
-      }
-      if (apiKeyTouched()) {
-        setApiKeyTouched(false)
-      }
-      if (clearStoredApiKey()) {
-        setClearStoredApiKey(false)
+      const adjustedDrafts = serverSupportsSeparateProviders()
+        ? nextDrafts
+        : { ...nextDrafts, separateProviders: false }
+      if (!isDraftEqual(drafts(), adjustedDrafts)) {
+        setDrafts(adjustedDrafts)
       }
+      if (apiKeyTouched()) setApiKeyTouched(false)
+      if (clearStoredApiKey()) setClearStoredApiKey(false)
+      if (sttApiKeyTouched()) setSttApiKeyTouched(false)
+      if (clearSttApiKey()) setClearSttApiKey(false)
+      if (ttsApiKeyTouched()) setTtsApiKeyTouched(false)
+      if (clearTtsApiKey()) setClearTtsApiKey(false)
     }
   })
 
@@ -85,7 +128,13 @@ export const SpeechSettingsCard: Component = () => {
   const capabilityLabel = () => {
     if (speechCapabilitiesLoading()) return t("settings.speech.status.loading")
     if (speechCapabilitiesError()) return t("settings.speech.status.error")
-    return speechCapabilities()?.configured ? t("settings.speech.status.configured") : t("settings.speech.status.missing")
+    const caps = speechCapabilities()
+    if (caps?.separateProviders) {
+      if (caps.sttConfigured && caps.ttsConfigured) return t("settings.speech.status.configured")
+      if (caps.sttConfigured || caps.ttsConfigured) return t("settings.speech.status.partial")
+      return t("settings.speech.status.missing")
+    }
+    return caps?.configured ? t("settings.speech.status.configured") : t("settings.speech.status.missing")
   }
 
   const updateDraft = (key: keyof DraftFields, value: string) => {
@@ -97,6 +146,23 @@ export const SpeechSettingsCard: Component = () => {
     setDrafts((current) => ({ ...current, [key]: value }))
   }
 
+  const updateDirectionalDraft = (dir: "stt" | "tts", key: keyof DirectionalDraft, value: string) => {
+    setSaveStatus("idle")
+    if (key === "apiKey") {
+      if (dir === "stt") {
+        setSttApiKeyTouched(true)
+        setClearSttApiKey(false)
+      } else {
+        setTtsApiKeyTouched(true)
+        setClearTtsApiKey(false)
+      }
+    }
+    setDrafts((current) => ({
+      ...current,
+      [dir]: { ...current[dir], [key]: value },
+    }))
+  }
+
   const apiKeyDirty = createMemo(() => clearStoredApiKey() || drafts().apiKey.trim().length > 0)
   const playbackSupport = createMemo(() =>
     getSpeechPlaybackSupport({
@@ -107,7 +173,7 @@ export const SpeechSettingsCard: Component = () => {
   )
   const compatibilityMessage = createMemo(() => {
     const capabilities = speechCapabilities()
-    if (!capabilities?.available || !capabilities?.configured || !capabilities?.supportsTts) {
+    if (!capabilities?.available || !capabilities?.ttsConfigured || !capabilities?.supportsTts) {
       return null
     }
     if (drafts().playbackMode === "streaming" && !capabilities.supportsStreamingTts) {
@@ -122,6 +188,28 @@ export const SpeechSettingsCard: Component = () => {
   const isDirty = createMemo(() => {
     const speech = serverSettings().speech
     const current = drafts()
+
+    if (current.separateProviders !== speech.separateProviders) return true
+
+    if (current.separateProviders) {
+      const sttDir = speech.stt
+      const ttsDir = speech.tts
+      const sttDirty =
+        clearSttApiKey() ||
+        current.stt.apiKey.trim().length > 0 ||
+        (current.stt.baseUrl || "") !== (sttDir.baseUrl || "") ||
+        current.stt.model !== sttDir.model
+      const ttsDirty =
+        clearTtsApiKey() ||
+        current.tts.apiKey.trim().length > 0 ||
+        (current.tts.baseUrl || "") !== (ttsDir.baseUrl || "") ||
+        current.tts.model !== ttsDir.model ||
+        current.ttsVoice !== speech.ttsVoice ||
+        current.playbackMode !== speech.playbackMode ||
+        current.ttsFormat !== speech.ttsFormat
+      return sttDirty || ttsDirty
+    }
+
     return (
       apiKeyDirty() ||
       (current.baseUrl || "") !== (speech.baseUrl || "") ||
@@ -143,31 +231,46 @@ export const SpeechSettingsCard: Component = () => {
   async function handleSave() {
     if (!isDirty() || isSaving()) return
     const current = drafts()
+    const saved = serverSettings().speech
+
     setIsSaving(true)
     setSaveStatus("idle")
     try {
-      const trimmedApiKey = current.apiKey.trim()
-      await updateSpeechSettings({
-        ...(clearStoredApiKey() ? { apiKey: null } : trimmedApiKey ? { apiKey: trimmedApiKey } : {}),
-        baseUrl: current.baseUrl.trim() || undefined,
-        sttModel: current.sttModel.trim() || undefined,
-        ttsModel: current.ttsModel.trim() || undefined,
-        ttsVoice: current.ttsVoice.trim() || undefined,
-        playbackMode: current.playbackMode,
-        ttsFormat: current.ttsFormat,
-      })
+      if (current.separateProviders) {
+        await updateSpeechSettings({
+          separateProviders: true,
+          stt: buildDirSave(clearSttApiKey(), current.stt.apiKey, current.stt.baseUrl, current.stt.model, saved.stt.baseUrl, saved.sttModel),
+          tts: buildDirSave(clearTtsApiKey(), current.tts.apiKey, current.tts.baseUrl, current.tts.model, saved.tts.baseUrl, saved.ttsModel),
+          ...(current.sttModel !== saved.sttModel ? { sttModel: current.sttModel.trim() || null } : {}),
+          ...(current.ttsModel !== saved.ttsModel ? { ttsModel: current.ttsModel.trim() || null } : {}),
+          ...(current.baseUrl !== (saved.baseUrl || "") ? { baseUrl: current.baseUrl.trim() || null, ...(clearStoredApiKey() ? {} : current.apiKey.trim() ? {} : { apiKey: null }) } : {}),
+          ...(clearStoredApiKey() ? { apiKey: null } : current.apiKey.trim() ? { apiKey: current.apiKey.trim() } : {}),
+          ttsVoice: current.ttsVoice.trim() || null,
+          playbackMode: current.playbackMode,
+          ttsFormat: current.ttsFormat,
+        })
+      } else {
+        const trimmedApiKey = current.apiKey.trim()
+        const baseUrlChanged = (current.baseUrl.trim() || "") !== (saved.baseUrl || "")
+        await updateSpeechSettings({
+          separateProviders: false,
+          ...(clearStoredApiKey() ? { apiKey: null } : trimmedApiKey ? { apiKey: trimmedApiKey } : baseUrlChanged ? { apiKey: null } : {}),
+          ...(baseUrlChanged ? { baseUrl: current.baseUrl.trim() || null } : {}),
+          sttModel: current.sttModel.trim() || null,
+          ttsModel: current.ttsModel.trim() || null,
+          ttsVoice: current.ttsVoice.trim() || null,
+          playbackMode: current.playbackMode,
+          ttsFormat: current.ttsFormat,
+        })
+      }
       await loadSpeechCapabilities(true)
-      setDrafts({
-        apiKey: "",
-        baseUrl: current.baseUrl.trim(),
-        sttModel: current.sttModel.trim() || serverSettings().speech.sttModel,
-        ttsModel: current.ttsModel.trim() || serverSettings().speech.ttsModel,
-        ttsVoice: current.ttsVoice.trim() || serverSettings().speech.ttsVoice,
-        playbackMode: current.playbackMode,
-        ttsFormat: current.ttsFormat,
-      })
+      setDrafts(createDraftFields(serverSettings().speech))
       setApiKeyTouched(false)
       setClearStoredApiKey(false)
+      setSttApiKeyTouched(false)
+      setClearSttApiKey(false)
+      setTtsApiKeyTouched(false)
+      setClearTtsApiKey(false)
       setSaveStatus("saved")
     } catch (error) {
       log.error("Failed to save speech settings", error)
@@ -200,6 +303,38 @@ export const SpeechSettingsCard: Component = () => {
             <span class="settings-inline-note">{t("settings.speech.provider.openaiCompatible")}</span>
             <span class="settings-inline-note">{capabilityLabel()}</span>
             <span class="settings-inline-note">{saveStatusLabel()}</span>
+            <button
+              type="button"
+              class="selector-button selector-button-secondary w-auto whitespace-nowrap inline-flex items-center gap-2"
+              onClick={() => void testTranscription.toggle()}
+              disabled={(isSaving() && testTranscription.state() !== "recording") || testTranscription.state() === "requesting" || testTranscription.state() === "transcribing" || (testTranscription.state() === "idle" && !testTranscription.canUseTranscription())}
+              title={testTranscription.buttonTitle()}
+              aria-label={testTranscription.buttonTitle()}
+            >
+              <Show
+                when={testTranscription.isTranscribing() || testTranscription.state() === "requesting"}
+                fallback={
+                  <Show
+                    when={testTranscription.isRecording()}
+                    fallback={<Mic class="w-3.5 h-3.5" aria-hidden="true" />}
+                  >
+                    <Square class="w-3.5 h-3.5" aria-hidden="true" />
+                  </Show>
+                }
+              >
+                <Loader2 class="w-3.5 h-3.5 animate-spin" aria-hidden="true" />
+              </Show>
+              <span>
+                {testTranscription.buttonTitle()}
+              </span>
+            </button>
+            <Show when={testTranscription.result()}>
+              {(text) => (
+                <span class="settings-inline-note" title={text()}>
+                  {text().length > 40 ? `${text().slice(0, 40)}…` : text()}
+                </span>
+              )}
+            </Show>
             <button
               type="button"
               class="selector-button selector-button-secondary w-auto whitespace-nowrap inline-flex items-center gap-2"
@@ -237,57 +372,174 @@ export const SpeechSettingsCard: Component = () => {
           </div>
         </div>
 
-        <Field
-          label={t("settings.speech.apiKey.title")}
-          caption={t("settings.speech.apiKey.subtitle")}
-          value={drafts().apiKey}
-          onInput={(value) => updateDraft("apiKey", value)}
-          type="password"
-          placeholder={serverSettings().speech.hasApiKey ? t("settings.speech.apiKey.placeholder") : undefined}
-        />
-        <Show when={serverSettings().speech.hasApiKey && !apiKeyTouched() && drafts().apiKey.length === 0}>
-          <div class="settings-inline-note">
-            {clearStoredApiKey() ? t("settings.speech.apiKey.clearPending") : t("settings.speech.apiKey.storedNote")}{" "}
-            <Show when={!clearStoredApiKey()}>
-              <button
-                type="button"
-                class="selector-button selector-button-secondary w-auto whitespace-nowrap"
-                onClick={() => {
-                  setClearStoredApiKey(true)
+        <Show when={serverSupportsSeparateProviders()}>
+          <div class="settings-toggle-row settings-toggle-row-compact">
+            <div>
+              <div class="settings-toggle-title">{t("settings.speech.separateProviders.title")}</div>
+              <div class="settings-toggle-caption">{t("settings.speech.separateProviders.subtitle")}</div>
+            </div>
+            <label class="settings-checkbox-toggle">
+              <input
+                type="checkbox"
+                checked={drafts().separateProviders}
+                disabled={isSaving()}
+                onChange={(event) => {
                   setSaveStatus("idle")
+                  setDrafts((current) => ({ ...current, separateProviders: event.currentTarget.checked }))
                 }}
-              >
-                {t("settings.speech.apiKey.clearAction")}
-              </button>
-            </Show>
+              />
+              <span>{t("settings.common.enabled")}</span>
+            </label>
           </div>
         </Show>
-        <Field
-          label={t("settings.speech.baseUrl.title")}
-          caption={t("settings.speech.baseUrl.subtitle")}
-          value={drafts().baseUrl}
-          onInput={(value) => updateDraft("baseUrl", value)}
-          placeholder={t("settings.speech.baseUrl.placeholder")}
-        />
-        <Field
-          label={t("settings.speech.sttModel.title")}
-          caption={t("settings.speech.sttModel.subtitle")}
-          value={drafts().sttModel}
-          onInput={(value) => updateDraft("sttModel", value)}
-        />
-        <Field
-          label={t("settings.speech.ttsModel.title")}
-          caption={t("settings.speech.ttsModel.subtitle")}
-          value={drafts().ttsModel}
-          onInput={(value) => updateDraft("ttsModel", value)}
-        />
-        <Field
-          label={t("settings.speech.ttsVoice.title")}
-          caption={t("settings.speech.ttsVoice.subtitle")}
-          value={drafts().ttsVoice}
-          onInput={(value) => updateDraft("ttsVoice", value)}
-          icon={<Mic class="w-3.5 h-3.5 icon-muted flex-shrink-0" />}
-        />
+
+        <Show when={!drafts().separateProviders}>
+          <Field
+            label={t("settings.speech.apiKey.title")}
+            caption={t("settings.speech.apiKey.subtitle")}
+            value={drafts().apiKey}
+            onInput={(value) => updateDraft("apiKey", value)}
+            type="password"
+            placeholder={serverSettings().speech.hasApiKey ? t("settings.speech.apiKey.placeholder") : undefined}
+          />
+          <Show when={serverSettings().speech.hasApiKey && !apiKeyTouched() && drafts().apiKey.length === 0}>
+            <div class="settings-inline-note">
+              {clearStoredApiKey() ? t("settings.speech.apiKey.clearPending") : t("settings.speech.apiKey.storedNote")}{" "}
+              <Show when={!clearStoredApiKey()}>
+                <button
+                  type="button"
+                  class="selector-button selector-button-secondary w-auto whitespace-nowrap"
+                  onClick={() => { setClearStoredApiKey(true); setSaveStatus("idle") }}
+                >
+                  {t("settings.speech.apiKey.clearAction")}
+                </button>
+              </Show>
+            </div>
+          </Show>
+          <Field
+            label={t("settings.speech.baseUrl.title")}
+            caption={t("settings.speech.baseUrl.subtitle")}
+            value={drafts().baseUrl}
+            onInput={(value) => updateDraft("baseUrl", value)}
+            placeholder={t("settings.speech.baseUrl.placeholder")}
+          />
+          <Field
+            label={t("settings.speech.sttModel.title")}
+            caption={t("settings.speech.sttModel.subtitle")}
+            value={drafts().sttModel}
+            onInput={(value) => updateDraft("sttModel", value)}
+          />
+          <Field
+            label={t("settings.speech.ttsModel.title")}
+            caption={t("settings.speech.ttsModel.subtitle")}
+            value={drafts().ttsModel}
+            onInput={(value) => updateDraft("ttsModel", value)}
+          />
+          <Field
+            label={t("settings.speech.ttsVoice.title")}
+            caption={t("settings.speech.ttsVoice.subtitle")}
+            value={drafts().ttsVoice}
+            onInput={(value) => updateDraft("ttsVoice", value)}
+            icon={<Mic class="w-3.5 h-3.5 icon-muted flex-shrink-0" />}
+          />
+        </Show>
+
+        <Show when={drafts().separateProviders && serverSupportsSeparateProviders()}>
+          <div class="settings-card-section-header">
+            <h4 class="settings-card-section-title">{t("settings.speech.stt.section.title")}</h4>
+          </div>
+          <Field
+            label={t("settings.speech.stt.apiKey.title")}
+            caption={t("settings.speech.stt.apiKey.subtitle")}
+            value={drafts().stt.apiKey}
+            onInput={(value) => updateDirectionalDraft("stt", "apiKey", value)}
+            type="password"
+            placeholder={(serverSettings().speech.stt.hasApiKey || serverSettings().speech.hasApiKey) ? t("settings.speech.stt.apiKey.placeholder") : undefined}
+          />
+          <Show when={(serverSettings().speech.stt.hasApiKey || serverSettings().speech.hasApiKey) && !sttApiKeyTouched() && drafts().stt.apiKey.length === 0}>
+            <div class="settings-inline-note">
+              <Show
+                when={serverSettings().speech.stt.hasApiKey}
+                fallback={t("settings.speech.stt.apiKey.usingShared")}
+              >
+                {clearSttApiKey() ? t("settings.speech.stt.apiKey.clearPending") : t("settings.speech.stt.apiKey.storedNote")}{" "}
+                <Show when={!clearSttApiKey()}>
+                  <button
+                    type="button"
+                    class="selector-button selector-button-secondary w-auto whitespace-nowrap"
+                    onClick={() => { setClearSttApiKey(true); setSaveStatus("idle") }}
+                  >
+                    {t("settings.speech.stt.apiKey.clearAction")}
+                  </button>
+                </Show>
+              </Show>
+            </div>
+          </Show>
+          <Field
+            label={t("settings.speech.stt.baseUrl.title")}
+            caption={t("settings.speech.stt.baseUrl.subtitle")}
+            value={drafts().stt.baseUrl}
+            onInput={(value) => updateDirectionalDraft("stt", "baseUrl", value)}
+            placeholder={t("settings.speech.stt.baseUrl.placeholder")}
+          />
+          <Field
+            label={t("settings.speech.stt.model.title")}
+            caption={t("settings.speech.stt.model.subtitle")}
+            value={drafts().stt.model}
+            onInput={(value) => updateDirectionalDraft("stt", "model", value)}
+          />
+
+          <div class="settings-card-section-header">
+            <h4 class="settings-card-section-title">{t("settings.speech.tts.section.title")}</h4>
+          </div>
+          <Field
+            label={t("settings.speech.tts.apiKey.title")}
+            caption={t("settings.speech.tts.apiKey.subtitle")}
+            value={drafts().tts.apiKey}
+            onInput={(value) => updateDirectionalDraft("tts", "apiKey", value)}
+            type="password"
+            placeholder={(serverSettings().speech.tts.hasApiKey || serverSettings().speech.hasApiKey) ? t("settings.speech.tts.apiKey.placeholder") : undefined}
+          />
+          <Show when={(serverSettings().speech.tts.hasApiKey || serverSettings().speech.hasApiKey) && !ttsApiKeyTouched() && drafts().tts.apiKey.length === 0}>
+            <div class="settings-inline-note">
+              <Show
+                when={serverSettings().speech.tts.hasApiKey}
+                fallback={t("settings.speech.tts.apiKey.usingShared")}
+              >
+                {clearTtsApiKey() ? t("settings.speech.tts.apiKey.clearPending") : t("settings.speech.tts.apiKey.storedNote")}{" "}
+                <Show when={!clearTtsApiKey()}>
+                  <button
+                    type="button"
+                    class="selector-button selector-button-secondary w-auto whitespace-nowrap"
+                    onClick={() => { setClearTtsApiKey(true); setSaveStatus("idle") }}
+                  >
+                    {t("settings.speech.tts.apiKey.clearAction")}
+                  </button>
+                </Show>
+              </Show>
+            </div>
+          </Show>
+          <Field
+            label={t("settings.speech.tts.baseUrl.title")}
+            caption={t("settings.speech.tts.baseUrl.subtitle")}
+            value={drafts().tts.baseUrl}
+            onInput={(value) => updateDirectionalDraft("tts", "baseUrl", value)}
+            placeholder={t("settings.speech.tts.baseUrl.placeholder")}
+          />
+          <Field
+            label={t("settings.speech.tts.model.title")}
+            caption={t("settings.speech.tts.model.subtitle")}
+            value={drafts().tts.model}
+            onInput={(value) => updateDirectionalDraft("tts", "model", value)}
+          />
+          <Field
+            label={t("settings.speech.ttsVoice.title")}
+            caption={t("settings.speech.ttsVoice.subtitle")}
+            value={drafts().ttsVoice}
+            onInput={(value) => updateDraft("ttsVoice", value)}
+            icon={<Mic class="w-3.5 h-3.5 icon-muted flex-shrink-0" />}
+          />
+        </Show>
         <SelectField
           label={t("settings.speech.playbackMode.title")}
           caption={t("settings.speech.playbackMode.subtitle")}
diff --git a/packages/ui/src/components/settings/speech-settings-section.tsx b/packages/ui/src/components/settings/speech-settings-section.tsx
index 939b279c..681161e5 100644
--- a/packages/ui/src/components/settings/speech-settings-section.tsx
+++ b/packages/ui/src/components/settings/speech-settings-section.tsx
@@ -1,9 +1,22 @@
-import type { Component } from "solid-js"
+import { createMemo, type Component } from "solid-js"
+import { getBehaviorSettings } from "../../lib/settings/behavior-registry"
+import { useConfig } from "../../stores/preferences"
+import { BehaviorSettingRows } from "./behavior-setting-rows"
 import SpeechSettingsCard from "./speech-settings-card"
 
 export const SpeechSettingsSection: Component = () => {
+  const config = useConfig()
+  const voiceSettings = createMemo(() =>
+    getBehaviorSettings(config).filter((setting) => setting.id === "behavior.promptVoiceInput"),
+  )
+
   return (
     <div class="settings-section-stack">
+      <div class="settings-card">
+        <div class="settings-stack">
+          <BehaviorSettingRows settings={voiceSettings} preferences={config.preferences} />
+        </div>
+      </div>
       <SpeechSettingsCard />
     </div>
   )
diff --git a/packages/ui/src/components/settings/startup-state-settings-card.tsx b/packages/ui/src/components/settings/startup-state-settings-card.tsx
new file mode 100644
index 00000000..97146914
--- /dev/null
+++ b/packages/ui/src/components/settings/startup-state-settings-card.tsx
@@ -0,0 +1,82 @@
+import { createSignal, type Component } from "solid-js"
+import { useI18n } from "../../lib/i18n"
+import { showToastNotification } from "../../lib/notifications"
+import {
+  clearRestoredClientState,
+  clientStateIsPrimary,
+  restorePreviousStateEnabled,
+  setRestorePreviousStateEnabled,
+} from "../../stores/client-state"
+
+export const StartupStateSettingsCard: Component = () => {
+  const { t } = useI18n()
+  const [busy, setBusy] = createSignal(false)
+
+  const updateRestoreSetting = async (enabled: boolean) => {
+    setBusy(true)
+    try {
+      await setRestorePreviousStateEnabled(enabled)
+    } catch {
+      showToastNotification({ message: t("settings.appearance.startup.updateError"), variant: "error" })
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const clearStartupState = async () => {
+    setBusy(true)
+    try {
+      await clearRestoredClientState()
+      showToastNotification({ message: t("settings.appearance.startup.clearSuccess"), variant: "success" })
+    } catch {
+      showToastNotification({ message: t("settings.appearance.startup.clearError"), variant: "error" })
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div class="settings-card">
+      <div class="settings-card-header">
+        <div>
+          <h3 class="settings-card-title">{t("settings.appearance.startup.title")}</h3>
+          <p class="settings-card-subtitle">{t("settings.appearance.startup.subtitle")}</p>
+        </div>
+        <span class="settings-scope-badge">{t("settings.scope.device")}</span>
+      </div>
+
+      <div class="settings-stack">
+        <div class="settings-toggle-row">
+          <div>
+            <div class="settings-toggle-title">{t("settings.appearance.startup.restore.title")}</div>
+            <div class="settings-toggle-caption">{t("settings.appearance.startup.restore.subtitle")}</div>
+          </div>
+          <label class="settings-checkbox-toggle">
+            <input
+              type="checkbox"
+              checked={restorePreviousStateEnabled()}
+              disabled={busy() || !clientStateIsPrimary()}
+              onChange={(event) => void updateRestoreSetting(event.currentTarget.checked)}
+            />
+            <span>{restorePreviousStateEnabled() ? t("settings.common.enabled") : t("settings.common.disabled")}</span>
+          </label>
+        </div>
+
+        <div class="settings-toggle-row">
+          <div>
+            <div class="settings-toggle-title">{t("settings.appearance.startup.clear.title")}</div>
+            <div class="settings-toggle-caption">{t("settings.appearance.startup.clear.subtitle")}</div>
+          </div>
+          <button
+            type="button"
+            class="selector-button selector-button-secondary w-auto whitespace-nowrap"
+            disabled={busy() || !clientStateIsPrimary()}
+            onClick={() => void clearStartupState()}
+          >
+            {t("settings.appearance.startup.clear.action")}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/packages/ui/src/components/toast-history-panel.tsx b/packages/ui/src/components/toast-history-panel.tsx
index 7e7d9115..381fe3c1 100644
--- a/packages/ui/src/components/toast-history-panel.tsx
+++ b/packages/ui/src/components/toast-history-panel.tsx
@@ -21,9 +21,9 @@ import {
   deleteToastHistoryItem,
   markAllToastHistoryAsRead,
   markToastHistoryAsRead,
+  runToastAction,
   subscribeToastHistory,
 } from "../lib/notifications"
-import { isTauriHost } from "../lib/runtime-env"
 
 // ==================== Types ====================
 
@@ -182,15 +182,9 @@ const ToastHistoryPanel: Component<ToastHistoryPanelProps> = (props) => {
 
   // Handle item click
   const handleItemClick = (item: IToastHistoryItem) => {
-    // Mark as read
     if (!item.read) {
       markToastHistoryAsRead(item.id);
     }
-
-    // Open action link if exists
-    if (item.action?.href) {
-      void handleOpenAction(item.action.href);
-    }
   };
 
   // Handle delete
@@ -209,21 +203,6 @@ const ToastHistoryPanel: Component<ToastHistoryPanelProps> = (props) => {
     markAllToastHistoryAsRead();
   };
 
-  // Open external link
-  async function handleOpenAction(href: string): Promise<void> {
-    if (isTauriHost()) {
-      try {
-        const { openUrl } = await import("@tauri-apps/plugin-opener");
-        await openUrl(href);
-        return;
-      } catch (error) {
-        console.warn("[toast-history] unable to open via system opener", error);
-      }
-    }
-
-    window.open(href, "_blank", "noopener,noreferrer");
-  }
-
   // Stop click propagation from backdrop to panel
   const handleBackdropClick = (event: MouseEvent) => {
     if (event.target === event.currentTarget) {
@@ -383,8 +362,8 @@ const ToastHistoryPanel: Component<ToastHistoryPanelProps> = (props) => {
                                   class="toast-history-item-action inline-flex items-center gap-1 text-xs mt-1"
                                   onClick={(e) => {
                                     e.stopPropagation();
-                                    if (item.action?.href) {
-                                      void handleOpenAction(item.action.href);
+                                    if (item.action) {
+                                      void runToastAction(item.action);
                                     }
                                   }}
                                 >
diff --git a/packages/ui/src/components/tool-call.tsx b/packages/ui/src/components/tool-call.tsx
index a042156e..0446ca23 100644
--- a/packages/ui/src/components/tool-call.tsx
+++ b/packages/ui/src/components/tool-call.tsx
@@ -12,7 +12,7 @@ import { getPermissionSessionId } from "../types/permission"
 import type { QuestionRequest } from "../types/question"
 import { useI18n } from "../lib/i18n"
 import { resolveToolRenderer } from "./tool-call/renderers"
-import { resolveToolExpansionDefault } from "./tool-call/tool-registry"
+import { resolveToolExpansionDefault, resolveToolVisibility } from "./tool-call/tool-registry"
 import { QuestionToolBlock } from "./tool-call/question-block"
 import { PermissionToolBlock } from "./tool-call/permission-block"
 import { createAnsiContentRenderer } from "./tool-call/ansi-render"
@@ -52,7 +52,6 @@ const log = getLogger("session")
 type ToolState = import("@opencode-ai/sdk/v2").ToolState
 
 const TOOL_CALL_CACHE_SCOPE = "tool-call"
-const TOOL_SCROLL_SENTINEL_MARGIN_PX = 48
 
 function makeRenderCacheKey(
   toolCallId?: string | null,
@@ -194,7 +193,6 @@ function ToolCallDetails(props: {
   const followScroll = createFollowScroll({
     getScrollTopSnapshot: props.scrollTopSnapshot,
     setScrollTopSnapshot: props.setScrollTopSnapshot,
-    sentinelMarginPx: TOOL_SCROLL_SENTINEL_MARGIN_PX,
     sentinelClassName: "tool-call-scroll-sentinel",
   })
 
@@ -746,7 +744,9 @@ export default function ToolCall(props: ToolCallProps) {
     return undefined
   })
 
-  const diagnosticsDefaultExpanded = createMemo(() => (preferences().diagnosticsExpansion || "expanded") === "expanded")
+  const diagnosticsVisibility = createMemo(() => preferences().diagnosticsExpansion || "expanded")
+  const diagnosticsDefaultExpanded = createMemo(() => diagnosticsVisibility() === "expanded")
+  const toolVisibility = createMemo(() => resolveToolVisibility(preferences(), toolCallMemo()?.tool || ""))
 
   const defaultExpandedForTool = createMemo(() => {
     if (props.forceCollapsed) {
@@ -795,6 +795,8 @@ export default function ToolCall(props: ToolCallProps) {
     return active?.kind === "question" && active.id === pending.request.id
   })
 
+  const isToolVisible = createMemo(() => toolVisibility() !== "hidden" || isPermissionActive() || isQuestionActive())
+
   const expanded = () => {
     if (isPermissionActive() || isQuestionActive()) return true
     const override = userExpanded()
@@ -1048,6 +1050,7 @@ export default function ToolCall(props: ToolCallProps) {
   const status = () => toolState()?.status || ""
 
   return (
+    <Show when={isToolVisible()}>
       <div
 
         ref={(element) => {
@@ -1170,7 +1173,7 @@ export default function ToolCall(props: ToolCallProps) {
         />
       </Show>
  
-      <Show when={diagnosticsEntries().length}>
+      <Show when={diagnosticsEntries().length && diagnosticsVisibility() !== "hidden"}>
 
         {renderDiagnosticsSection(
           t,
@@ -1184,5 +1187,6 @@ export default function ToolCall(props: ToolCallProps) {
         )}
       </Show>
     </div>
+    </Show>
   )
 }
diff --git a/packages/ui/src/components/tool-call/markdown-render.tsx b/packages/ui/src/components/tool-call/markdown-render.tsx
index a2f385d1..2c389ac4 100644
--- a/packages/ui/src/components/tool-call/markdown-render.tsx
+++ b/packages/ui/src/components/tool-call/markdown-render.tsx
@@ -30,7 +30,8 @@ export function createMarkdownContentRenderer(params: {
 
     const size = options.size || "default"
     const disableHighlight = options.disableHighlight || false
-    const messageClass = `message-text tool-call-markdown${size === "large" ? " tool-call-markdown-large" : ""}${options.wrap ? " tool-call-markdown-wrap" : ""}`
+    const wrapEnabled = options.wrap ?? true
+    const messageClass = `message-text tool-call-markdown${size === "large" ? " tool-call-markdown-large" : ""}${wrapEnabled ? " tool-call-markdown-wrap" : ""}`
     const state = params.toolState()
     const disableScrollTracking = options.disableScrollTracking || (state?.status !== "running" && state?.status !== "pending")
     const registerRef = disableScrollTracking ? registerUntracked : registerTracked
@@ -73,6 +74,7 @@ export function createMarkdownContentRenderer(params: {
           sessionId={params.sessionId}
           isDark={params.isDark()}
           disableHighlight={disableHighlight}
+          defaultCodeBlockWrap={wrapEnabled}
           onRendered={handleMarkdownRendered}
         />
         {params.scrollHelpers.renderSentinel({ disableTracking: disableScrollTracking })}
diff --git a/packages/ui/src/components/tool-call/tool-registry.ts b/packages/ui/src/components/tool-call/tool-registry.ts
index 2358e129..004a6c2c 100644
--- a/packages/ui/src/components/tool-call/tool-registry.ts
+++ b/packages/ui/src/components/tool-call/tool-registry.ts
@@ -1,4 +1,9 @@
-import type { ExpansionPreference, Preferences, ToolCallExpansionPreset } from "../../stores/preferences"
+import type {
+  ExpansionPreference,
+  Preferences,
+  ToolCallExpansionPreset,
+  VisibilityPreference,
+} from "../../stores/preferences"
 import type { ToolRenderer } from "./types"
 import { applyPatchRenderer } from "./renderers/apply-patch"
 import { bashRenderer } from "./renderers/bash"
@@ -30,14 +35,14 @@ export interface ToolRegistryEntry {
   labelKey?: string
   renderer: ToolRenderer
   configurable: boolean
-  expansionPresets: Record<ToolCallExpansionPreset, ExpansionPreference>
+  expansionPresets: Record<ToolCallExpansionPreset, VisibilityPreference>
   aliases?: string[]
 }
 
 const expanded = "expanded" satisfies ExpansionPreference
 const collapsed = "collapsed" satisfies ExpansionPreference
 
-function presets(values: Record<ToolCallExpansionPreset, ExpansionPreference>) {
+function presets(values: Record<ToolCallExpansionPreset, VisibilityPreference>) {
   return values
 }
 
@@ -172,26 +177,29 @@ export function getConfigurableToolEntries(): ToolRegistryEntry[] {
   return TOOL_REGISTRY.filter((entry) => entry.configurable)
 }
 
-export function buildToolExpansionPresetDefaults(preset: ToolCallExpansionPreset): Record<string, ExpansionPreference> {
-  const defaults: Record<string, ExpansionPreference> = {}
+export function buildToolExpansionPresetDefaults(preset: ToolCallExpansionPreset): Record<string, VisibilityPreference> {
+  const defaults: Record<string, VisibilityPreference> = {}
   for (const entry of getConfigurableToolEntries()) {
     defaults[entry.tool] = entry.expansionPresets[preset]
   }
   return defaults
 }
 
-export function resolveToolExpansionDefault(preferences: Preferences, toolName: string): boolean {
+export function resolveToolVisibility(preferences: Preferences, toolName: string): VisibilityPreference {
   const entry = getToolRegistryEntry(toolName)
   const defaults = preferences.toolCallExpansionDefaults
   const presetMode = defaults.preset === "custom" ? undefined : entry.expansionPresets[defaults.preset]
   const otherPresetMode = defaults.preset === "custom" ? undefined : otherToolEntry.expansionPresets[defaults.preset]
-  const mode = defaults.tools[entry.tool]
+  return defaults.tools[entry.tool]
     ?? presetMode
     ?? defaults.tools[OTHER_TOOL_NAME]
     ?? otherPresetMode
     ?? preferences.toolOutputExpansion
     ?? "expanded"
-  return mode === "expanded"
+}
+
+export function resolveToolExpansionDefault(preferences: Preferences, toolName: string): boolean {
+  return resolveToolVisibility(preferences, toolName) === "expanded"
 }
 
 export function resolveThinkingExpansionDefault(preferences: Preferences): boolean {
diff --git a/packages/ui/src/components/tool-deletion-companions.test.ts b/packages/ui/src/components/tool-deletion-companions.test.ts
new file mode 100644
index 00000000..3005ad2f
--- /dev/null
+++ b/packages/ui/src/components/tool-deletion-companions.test.ts
@@ -0,0 +1,135 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import {
+  collectToolDeletionCompanionPartIds,
+  executeBulkDeletionPlan,
+  type BulkDeletionPlan,
+} from "./tool-deletion-companions"
+
+function collect(parts: Array<{ id: string; type: string }>, selectedToolPartIds: string[]) {
+  const byId = new Map(parts.map((part) => [part.id, part]))
+  return collectToolDeletionCompanionPartIds(
+    parts.map((part) => part.id),
+    (partId) => byId.get(partId),
+    new Set(selectedToolPartIds),
+  )
+}
+
+describe("collectToolDeletionCompanionPartIds", () => {
+  it("collects reasoning and step-finish for a selected tool step", () => {
+    const result = collect([
+      { id: "start", type: "step-start" },
+      { id: "reasoning", type: "reasoning" },
+      { id: "tool", type: "tool" },
+      { id: "finish", type: "step-finish" },
+      { id: "text", type: "text" },
+    ], ["tool"])
+
+    assert.deepEqual([...result], ["reasoning", "finish"])
+  })
+
+  it("keeps shared companions when only one tool in a step is selected", () => {
+    const result = collect([
+      { id: "reasoning", type: "reasoning" },
+      { id: "tool-a", type: "tool" },
+      { id: "tool-b", type: "tool" },
+      { id: "finish", type: "step-finish" },
+    ], ["tool-a"])
+
+    assert.deepEqual([...result], [])
+  })
+
+  it("collects shared companions when every tool in the step is selected", () => {
+    const result = collect([
+      { id: "reasoning", type: "reasoning" },
+      { id: "tool-a", type: "tool" },
+      { id: "tool-b", type: "tool" },
+      { id: "finish", type: "step-finish" },
+    ], ["tool-a", "tool-b"])
+
+    assert.deepEqual([...result], ["reasoning", "finish"])
+  })
+
+  it("does not collect companions from an unselected adjacent step", () => {
+    const result = collect([
+      { id: "start-a", type: "step-start" },
+      { id: "reasoning-a", type: "reasoning" },
+      { id: "tool-a", type: "tool" },
+      { id: "finish-a", type: "step-finish" },
+      { id: "start-b", type: "step-start" },
+      { id: "reasoning-b", type: "reasoning" },
+      { id: "tool-b", type: "tool" },
+      { id: "finish-b", type: "step-finish" },
+    ], ["tool-a"])
+
+    assert.deepEqual([...result], ["reasoning-a", "finish-a"])
+  })
+})
+
+describe("executeBulkDeletionPlan", () => {
+  const plan: BulkDeletionPlan = {
+    messageIds: ["message"],
+    companionParts: [
+      { messageId: "assistant", partId: "reasoning" },
+      { messageId: "assistant", partId: "finish" },
+    ],
+    toolParts: [{ messageId: "assistant", partId: "tool" }],
+  }
+
+  it("clears positional selection and deletes companions before tools", async () => {
+    const events: string[] = []
+
+    await executeBulkDeletionPlan(plan, {
+      clearSelection: () => events.push("clear"),
+      deleteMessage: async (messageId) => { events.push(`message:${messageId}`) },
+      deletePart: async ({ partId }) => { events.push(`part:${partId}`) },
+    })
+
+    assert.deepEqual(events, [
+      "clear",
+      "message:message",
+      "part:reasoning",
+      "part:finish",
+      "part:tool",
+    ])
+  })
+
+  it("does not delete tools when companion cleanup fails", async () => {
+    const events: string[] = []
+
+    await assert.rejects(
+      executeBulkDeletionPlan(
+        { ...plan, messageIds: [] },
+        {
+          clearSelection: () => events.push("clear"),
+          deleteMessage: async () => {},
+          deletePart: async ({ partId }) => {
+            events.push(`part:${partId}`)
+            if (partId === "finish") throw new Error("failed companion")
+          },
+        },
+      ),
+      /failed companion/,
+    )
+
+    assert.deepEqual(events, ["clear", "part:reasoning", "part:finish"])
+  })
+
+  it("clears selection before a message deletion failure", async () => {
+    const events: string[] = []
+
+    await assert.rejects(
+      executeBulkDeletionPlan(plan, {
+        clearSelection: () => events.push("clear"),
+        deleteMessage: async () => {
+          events.push("message")
+          throw new Error("failed message")
+        },
+        deletePart: async ({ partId }) => { events.push(`part:${partId}`) },
+      }),
+      /failed message/,
+    )
+
+    assert.deepEqual(events, ["clear", "message"])
+  })
+})
diff --git a/packages/ui/src/components/tool-deletion-companions.ts b/packages/ui/src/components/tool-deletion-companions.ts
new file mode 100644
index 00000000..c7053e14
--- /dev/null
+++ b/packages/ui/src/components/tool-deletion-companions.ts
@@ -0,0 +1,74 @@
+type MessagePart = {
+  type?: string
+}
+
+export type MessagePartDeletionTarget = {
+  messageId: string
+  partId: string
+}
+
+export type BulkDeletionPlan = {
+  messageIds: readonly string[]
+  companionParts: readonly MessagePartDeletionTarget[]
+  toolParts: readonly MessagePartDeletionTarget[]
+}
+
+type BulkDeletionActions = {
+  clearSelection: () => void
+  deleteMessage: (messageId: string) => Promise<void>
+  deletePart: (target: MessagePartDeletionTarget) => Promise<void>
+}
+
+export async function executeBulkDeletionPlan(plan: BulkDeletionPlan, actions: BulkDeletionActions): Promise<void> {
+  // Timeline segment IDs are positional, so stale selections must not survive
+  // the first successful mutation and point at a different segment.
+  actions.clearSelection()
+
+  for (const messageId of plan.messageIds) {
+    await actions.deleteMessage(messageId)
+  }
+  for (const target of plan.companionParts) {
+    await actions.deletePart(target)
+  }
+  for (const target of plan.toolParts) {
+    await actions.deletePart(target)
+  }
+}
+
+export function collectToolDeletionCompanionPartIds(
+  partIds: readonly string[],
+  getPart: (partId: string) => MessagePart | undefined,
+  selectedToolPartIds: ReadonlySet<string>,
+): Set<string> {
+  const companions = new Set<string>()
+  let stepPartIds: string[] = []
+
+  const flushStep = () => {
+    const toolPartIds = stepPartIds.filter((partId) => getPart(partId)?.type === "tool")
+    if (toolPartIds.length > 0 && toolPartIds.every((partId) => selectedToolPartIds.has(partId))) {
+      for (const partId of stepPartIds) {
+        const type = getPart(partId)?.type
+        if (type === "reasoning" || type === "step-finish") {
+          companions.add(partId)
+        }
+      }
+    }
+    stepPartIds = []
+  }
+
+  for (const partId of partIds) {
+    const type = getPart(partId)?.type
+    if (type === "step-start") {
+      flushStep()
+      continue
+    }
+
+    stepPartIds.push(partId)
+    if (type === "step-finish") {
+      flushStep()
+    }
+  }
+
+  flushStep()
+  return companions
+}
diff --git a/packages/ui/src/components/unified-picker.tsx b/packages/ui/src/components/unified-picker.tsx
index b06e54a7..6c9e5837 100644
--- a/packages/ui/src/components/unified-picker.tsx
+++ b/packages/ui/src/components/unified-picker.tsx
@@ -443,7 +443,7 @@ const UnifiedPicker: Component<UnifiedPickerProps> = (props) => {
     <Show when={props.open}>
       <div
         ref={containerRef}
-        class="dropdown-surface bottom-full left-0 mb-1 max-w-md"
+        class="dropdown-surface bottom-full left-0 mb-1"
       >
         <div class="dropdown-header">
           <div class="dropdown-header-title">
@@ -456,7 +456,7 @@ const UnifiedPicker: Component<UnifiedPickerProps> = (props) => {
           </div>
         </div>
 
-        <div ref={scrollContainerRef} class="dropdown-content max-h-60">
+        <div ref={scrollContainerRef} class="dropdown-content max-h-60 overflow-x-auto">
           <Show when={(mode() === "command" ? commandCount() === 0 : agentCount() === 0 && fileCount() === 0)}>
             <div class="dropdown-empty">{t("unifiedPicker.empty")}</div>
           </Show>
@@ -593,7 +593,7 @@ const UnifiedPicker: Component<UnifiedPickerProps> = (props) => {
                     data-picker-selected={itemIndex === selectedIndex()}
                     onClick={() => props.onSelect({ type: "file", file }, "click")}
                   >
-                    <div class="flex items-center gap-2 text-sm">
+                    <div class="flex min-w-full w-max items-center gap-2 text-sm">
                       <Show
                         when={isFolder}
                         fallback={
@@ -616,7 +616,7 @@ const UnifiedPicker: Component<UnifiedPickerProps> = (props) => {
                           />
                         </svg>
                       </Show>
-                      <span class="truncate">{file.path}</span>
+                      <span class="whitespace-nowrap">{file.path}</span>
                     </div>
                   </div>
                 )
diff --git a/packages/ui/src/components/virtual-follow-behavior.test.ts b/packages/ui/src/components/virtual-follow-behavior.test.ts
index 79e18302..8c4ba262 100644
--- a/packages/ui/src/components/virtual-follow-behavior.test.ts
+++ b/packages/ui/src/components/virtual-follow-behavior.test.ts
@@ -2,214 +2,98 @@ import assert from "node:assert/strict"
 import { describe, it } from "node:test"
 
 import {
+  ANCHOR_RESTORE_MAX_FRAMES,
+  ANCHOR_RESTORE_STABLE_FRAMES,
+  AnchorRestoreStabilizer,
+  BOTTOM_FOLLOW_EPSILON_PX,
+  ScrollRestoreTokenGuard,
   VirtualScrollController,
   isAtBottom,
   isAutoFollowing,
+  isScrollRestoreGenerationCurrent,
+  isSnapshotAutoFollowing,
   resolveAutoPinHoldElement,
-  shouldSuspendAutoPinToBottomForHold,
+  restoreFollowModeFromSnapshot,
+  selectTopViewportAnchor,
   transitionFollowMode,
   type FollowMode,
   type ScrollControllerMetrics,
 } from "./virtual-follow-behavior.ts"
 
-const userScroll = (direction: "up" | "down" | null, atBottom: boolean, canPinToBottom = false) =>
-  ({ type: "user-scroll", direction, atBottom, canPinToBottom }) as const
+const userScroll = (direction: "up" | "down" | null, atBottom: boolean) =>
+  ({ type: "user-scroll", direction, atBottom }) as const
 
-function metrics(offset: number, scrollHeight = 3000, clientHeight = 600): ScrollControllerMetrics {
-  return {
-    offset,
-    scrollHeight,
-    clientHeight,
-    sentinelMarginPx: 48,
-  }
+function metrics(offset: number, scrollHeight = 3000, clientHeight = 600, sentinelMarginPx = BOTTOM_FOLLOW_EPSILON_PX): ScrollControllerMetrics {
+  return { offset, scrollHeight, clientHeight, sentinelMarginPx }
 }
 
 describe("virtual follow behavior", () => {
-  it("escapes follow on upward user scroll", () => {
-    const next = transitionFollowMode({ type: "following" }, userScroll("up", false))
+  it("escapes follow on any upward user intent", () => {
+    const next = transitionFollowMode({ type: "following" }, userScroll("up", true))
 
     assert.deepEqual(next.mode, { type: "escaped" })
     assert.deepEqual(next.effect, { type: "none" })
   })
 
-  it("does not rejoin follow when escaped user scrolls down above bottom without pin permission", () => {
+  it("does not rejoin follow from downward movement above the exact bottom", () => {
     const next = transitionFollowMode({ type: "escaped" }, userScroll("down", false))
 
     assert.deepEqual(next.mode, { type: "escaped" })
     assert.deepEqual(next.effect, { type: "none" })
   })
 
-  it("does not rejoin follow above bottom even with pin permission", () => {
-    const next = transitionFollowMode({ type: "escaped" }, userScroll("down", false, true))
-
-    assert.deepEqual(next.mode, { type: "escaped" })
-    assert.deepEqual(next.effect, { type: "none" })
-  })
-
-  it("rejoins follow when escaped user scrolls to the bottom", () => {
+  it("rejoins follow only at the exact bottom", () => {
     const next = transitionFollowMode({ type: "escaped" }, userScroll("down", true))
 
     assert.deepEqual(next.mode, { type: "following" })
     assert.deepEqual(next.effect, { type: "none" })
   })
 
-  it("keeps hold latched when the user scrolls down above bottom", () => {
-    const next = transitionFollowMode({ type: "holding", key: "message-1" }, userScroll("down", false, true))
-
-    assert.deepEqual(next.mode, { type: "holding", key: "message-1" })
-    assert.deepEqual(next.effect, { type: "none" })
-  })
-
-  it("does not rejoin follow for directionless scroll above bottom", () => {
-    const next = transitionFollowMode({ type: "escaped" }, userScroll(null, false, true))
-
-    assert.deepEqual(next.mode, { type: "escaped" })
-    assert.deepEqual(next.effect, { type: "none" })
-  })
-
-  it("does not rejoin follow on upward scroll at bottom", () => {
-    const next = transitionFollowMode({ type: "escaped" }, userScroll("up", true, true))
-
-    assert.deepEqual(next.mode, { type: "escaped" })
-    assert.deepEqual(next.effect, { type: "none" })
-  })
-
-  it("keeps hold latched for directionless user scroll away from bottom", () => {
-    const next = transitionFollowMode({ type: "holding", key: "message-1" }, userScroll(null, false, true))
-
-    assert.deepEqual(next.mode, { type: "holding", key: "message-1" })
-    assert.deepEqual(next.effect, { type: "none" })
-  })
-
   it("pins content growth while following but not while escaped", () => {
     const escaped = transitionFollowMode({ type: "escaped" }, { type: "content-grew", canPinToBottom: true })
     const following = transitionFollowMode({ type: "following" }, { type: "content-grew", canPinToBottom: true })
 
     assert.deepEqual(escaped.effect, { type: "none" })
-    assert.deepEqual(following.effect, { type: "scroll-bottom", immediate: true, suppressHold: false })
+    assert.deepEqual(following.effect, { type: "scroll-bottom", immediate: true })
   })
 
-  it("does not align or pin while held content grows", () => {
-    const next = transitionFollowMode({ type: "holding", key: "message-1" }, { type: "content-grew", canPinToBottom: true })
-
-    assert.deepEqual(next.mode, { type: "holding", key: "message-1" })
-    assert.deepEqual(next.effect, { type: "none" })
-  })
-
-  it("enters hold mode for a valid hold candidate", () => {
-    const next = transitionFollowMode({ type: "following" }, { type: "hold-candidate", key: "message-1", shouldHold: true })
-
-    assert.deepEqual(next.mode, { type: "holding", key: "message-1" })
-    assert.deepEqual(next.effect, { type: "align-hold", key: "message-1" })
-  })
-
-  it("keeps hold latched when the hold target disappears", () => {
-    const next = transitionFollowMode({ type: "holding", key: "message-1" }, { type: "hold-target-changed", key: null, canPinToBottom: true })
-
-    assert.deepEqual(next.mode, { type: "holding", key: "message-1" })
-    assert.deepEqual(next.effect, { type: "none" })
-  })
-
-  it("keeps hold latched when a later hold target is reported", () => {
-    const next = transitionFollowMode({ type: "holding", key: "message-1" }, { type: "hold-target-changed", key: "message-2", canPinToBottom: true })
-
-    assert.deepEqual(next.mode, { type: "holding", key: "message-1" })
-    assert.deepEqual(next.effect, { type: "none" })
-  })
-
-  it("explicit bottom jumps leave hold and suppress the next hold", () => {
-    const next = transitionFollowMode({ type: "holding", key: "message-1" }, { type: "jump-bottom", immediate: true, explicit: true })
+  it("does not pin content growth when the integration gate is closed", () => {
+    const next = transitionFollowMode({ type: "following" }, { type: "content-grew", canPinToBottom: false })
 
     assert.deepEqual(next.mode, { type: "following" })
-    assert.deepEqual(next.effect, { type: "scroll-bottom", immediate: true, suppressHold: true })
-  })
-
-  it("prompt submission overrides a stale hold latch and returns to bottom follow", () => {
-    const controller = new VirtualScrollController(true)
-    controller.holdCandidate("old-assistant-answer", true)
-
-    const result = controller.jumpBottom(true, true)
-
-    assert.deepEqual(result.state.mode, { type: "following" })
-    assert.deepEqual(result.effect, { type: "scroll-bottom", immediate: true, suppressHold: true })
-    assert.equal(controller.isAutoFollowing(), true)
-  })
-
-  it("clears an existing hold latch when hold targeting is disabled", () => {
-    const controller = new VirtualScrollController(true)
-    controller.holdCandidate("old-assistant-answer", true)
-
-    const result = controller.clearHold(true, true, true)
-
-    assert.deepEqual(result.state.mode, { type: "following" })
-    assert.deepEqual(result.effect, { type: "scroll-bottom", immediate: true, suppressHold: true })
-  })
-
-  it("keeps submitted prompt content growth in bottom-follow after clearing stale hold", () => {
-    const controller = new VirtualScrollController(true)
-    controller.holdCandidate("old-assistant-answer", true)
-    controller.jumpBottom(true, true)
-
-    const result = controller.contentRendered(metrics(2400), true)
-
-    assert.deepEqual(result.state.mode, { type: "following" })
-    assert.deepEqual(result.effect, { type: "scroll-bottom", immediate: true, suppressHold: false })
-  })
-
-  it("ignores stale previous assistant hold target changes after a submit bottom jump", () => {
-    const controller = new VirtualScrollController(true)
-    controller.holdCandidate("previous-assistant-answer", true)
-    controller.jumpBottom(true, true)
-
-    const targetChanged = controller.holdTargetChanged("previous-assistant-answer", true)
-    const contentRendered = controller.contentRendered(metrics(2400), true)
-
-    assert.deepEqual(targetChanged.state.mode, { type: "following" })
-    assert.deepEqual(targetChanged.effect, { type: "none" })
-    assert.deepEqual(contentRendered.state.mode, { type: "following" })
-    assert.deepEqual(contentRendered.effect, { type: "scroll-bottom", immediate: true, suppressHold: false })
-  })
-
-  it("keeps escaped-mode streaming detached until actual bottom", () => {
-    const suspend = shouldSuspendAutoPinToBottomForHold({
-      externalSuspend: false,
-      activeHoldTargetKey: null,
-      eligibleHoldTargetKey: "streaming-assistant-answer",
-    })
-
-    const next = transitionFollowMode({ type: "escaped" }, userScroll("down", false, !suspend))
-
-    assert.equal(suspend, false)
-    assert.deepEqual(next.mode, { type: "escaped" })
     assert.deepEqual(next.effect, { type: "none" })
   })
 
-  it("keeps auto-pin suspended while a hold target is actively latched", () => {
-    const suspend = shouldSuspendAutoPinToBottomForHold({
-      externalSuspend: false,
-      activeHoldTargetKey: "streaming-assistant-answer",
-      eligibleHoldTargetKey: "streaming-assistant-answer",
-    })
+  it("explicit bottom jumps enter follow mode", () => {
+    const next = transitionFollowMode({ type: "escaped" }, { type: "jump-bottom", immediate: true, explicit: true })
 
-    const next = transitionFollowMode({ type: "holding", key: "streaming-assistant-answer" }, userScroll("down", false, !suspend))
-
-    assert.equal(suspend, true)
-    assert.deepEqual(next.mode, { type: "holding", key: "streaming-assistant-answer" })
-    assert.deepEqual(next.effect, { type: "none" })
+    assert.deepEqual(next.mode, { type: "following" })
+    assert.deepEqual(next.effect, { type: "scroll-bottom", immediate: true })
   })
 
-  it("key jumps can opt into follow or escape mode", () => {
-    const follow = transitionFollowMode({ type: "escaped" }, { type: "jump-key", key: "a", block: "start", smooth: false, followAfter: true })
-    const escape = transitionFollowMode({ type: "following" }, { type: "jump-key", key: "b", block: "center", smooth: true, followAfter: false })
+  it("explicit bottom jumps override stale upward user intent", () => {
+    const controller = new VirtualScrollController(false)
+    controller.recordProgrammaticOffset(2200, false)
+    controller.setUserIntent("up", 700)
 
-    assert.deepEqual(follow.mode, { type: "following" })
-    assert.deepEqual(escape.mode, { type: "escaped" })
+    const jump = controller.jumpBottom(true, true)
+    const observed = controller.observeViewport(metrics(2400), 100, true)
+
+    assert.deepEqual(jump.state.mode, { type: "following" })
+    assert.deepEqual(observed.state.mode, { type: "following" })
   })
 
-  it("derives auto-follow from modes", () => {
+  it("key jumps always escape follow mode", () => {
+    const fromEscaped = transitionFollowMode({ type: "escaped" }, { type: "jump-key", key: "a", block: "start", smooth: false })
+    const fromFollowing = transitionFollowMode({ type: "following" }, { type: "jump-key", key: "b", block: "center", smooth: true })
+
+    assert.deepEqual(fromEscaped.mode, { type: "escaped" })
+    assert.deepEqual(fromFollowing.mode, { type: "escaped" })
+  })
+
+  it("derives auto-follow from the two modes", () => {
     const modes: Array<[FollowMode, boolean]> = [
       [{ type: "following" }, true],
-      [{ type: "holding", key: "message-1" }, false],
       [{ type: "escaped" }, false],
     ]
 
@@ -218,56 +102,6 @@ describe("virtual follow behavior", () => {
     }
   })
 
-  it("pins content growth instead of escaping on transient upward render movement", () => {
-    const controller = new VirtualScrollController(true)
-    controller.recordProgrammaticOffset(2400, true)
-
-    const result = controller.contentRendered(metrics(2200), true)
-
-    assert.deepEqual(result.state.mode, { type: "following" })
-    assert.deepEqual(result.effect, { type: "scroll-bottom", immediate: true, suppressHold: false })
-  })
-
-  it("does not align or pin when held content renders", () => {
-    const controller = new VirtualScrollController(true)
-    controller.holdCandidate("message-1", true)
-
-    const result = controller.contentRendered(metrics(2200), true)
-
-    assert.deepEqual(result.state.mode, { type: "holding", key: "message-1" })
-    assert.deepEqual(result.effect, { type: "none" })
-  })
-
-  it("does not resume or snap when a held target disappears", () => {
-    const controller = new VirtualScrollController(true)
-    controller.holdCandidate("message-1", true)
-
-    const result = controller.holdTargetChanged(null, true)
-
-    assert.deepEqual(result.state.mode, { type: "holding", key: "message-1" })
-    assert.deepEqual(result.effect, { type: "none" })
-  })
-
-  it("lets fresh user upward movement escape even during a programmatic window", () => {
-    const controller = new VirtualScrollController(true)
-    controller.recordProgrammaticOffset(2400, true)
-    controller.setUserIntent("up", 700)
-
-    const result = controller.observeViewport(metrics(2200), 100, true)
-
-    assert.deepEqual(result.state.mode, { type: "escaped" })
-  })
-
-  it("does not escape for owned programmatic upward movement", () => {
-    const controller = new VirtualScrollController(true)
-    controller.recordProgrammaticOffset(2400, true)
-
-    const result = controller.observeViewport(metrics(2200), 100, true)
-
-    assert.deepEqual(result.state.mode, { type: "following" })
-    assert.deepEqual(result.effect, { type: "none" })
-  })
-
   it("does not resume follow on directionless scroll above bottom", () => {
     const controller = new VirtualScrollController(false)
     controller.recordProgrammaticOffset(2220, false)
@@ -289,18 +123,7 @@ describe("virtual follow behavior", () => {
     assert.deepEqual(result.effect, { type: "none" })
   })
 
-  it("does not magnet to bottom above bottom even with integration pin permission", () => {
-    const controller = new VirtualScrollController(false)
-    controller.recordProgrammaticOffset(2100, false)
-    controller.setUserIntent("down", 700)
-
-    const result = controller.observeViewport(metrics(2220), 100, false, true)
-
-    assert.deepEqual(result.state.mode, { type: "escaped" })
-    assert.deepEqual(result.effect, { type: "none" })
-  })
-
-  it("resumes follow only when downward movement reaches actual bottom", () => {
+  it("resumes follow only when downward movement reaches exact bottom", () => {
     const controller = new VirtualScrollController(false)
     controller.recordProgrammaticOffset(2300, false)
     controller.setUserIntent("down", 700)
@@ -311,31 +134,33 @@ describe("virtual follow behavior", () => {
     assert.deepEqual(result.effect, { type: "none" })
   })
 
-  it("keeps hold latched until downward movement reaches actual bottom", () => {
+  it("lets fresh user upward movement escape even during a programmatic window", () => {
     const controller = new VirtualScrollController(true)
-    controller.holdCandidate("message-1", true)
-    controller.recordProgrammaticOffset(2100, false)
-    controller.setUserIntent("down", 700)
+    controller.recordProgrammaticOffset(2400, true)
+    controller.setUserIntent("up", 700)
 
-    const nearBottom = controller.observeViewport(metrics(2220), 100, false, true)
-
-    assert.deepEqual(nearBottom.state.mode, { type: "holding", key: "message-1" })
-    assert.deepEqual(nearBottom.effect, { type: "none" })
-
-    controller.setUserIntent("down", 800)
-    const atBottom = controller.observeViewport(metrics(2400), 200, false, true)
-
-    assert.deepEqual(atBottom.state.mode, { type: "following" })
-    assert.deepEqual(atBottom.effect, { type: "none" })
-  })
-
-  it("still escapes follow on upward movement at bottom", () => {
-    const controller = new VirtualScrollController(true)
-    controller.recordProgrammaticOffset(1200, false)
-
-    const result = controller.observeViewport(metrics(1100), 100, false)
+    const result = controller.observeViewport(metrics(2200), 100, true)
 
     assert.deepEqual(result.state.mode, { type: "escaped" })
+  })
+
+  it("keeps fresh upward intent escaped even if a programmatic scroll later moves down to bottom", () => {
+    const controller = new VirtualScrollController(false)
+    controller.recordProgrammaticOffset(2200, false)
+    controller.setUserIntent("up", 700)
+
+    const result = controller.observeViewport(metrics(2400), 100, true)
+
+    assert.deepEqual(result.state.mode, { type: "escaped" })
+  })
+
+  it("does not escape for owned programmatic upward movement", () => {
+    const controller = new VirtualScrollController(true)
+    controller.recordProgrammaticOffset(2400, true)
+
+    const result = controller.observeViewport(metrics(2200), 100, true)
+
+    assert.deepEqual(result.state.mode, { type: "following" })
     assert.deepEqual(result.effect, { type: "none" })
   })
 
@@ -349,33 +174,27 @@ describe("virtual follow behavior", () => {
     assert.deepEqual(result.effect, { type: "none" })
   })
 
-  it("does not pin content growth when the integration gate is closed", () => {
-    const controller = new VirtualScrollController(true)
+  it("uses a small bottom follow tolerance", () => {
+    const bottomOffset = 2400
 
-    const result = controller.contentRendered(metrics(2400), false)
-
-    assert.deepEqual(result.state.mode, { type: "following" })
-    assert.deepEqual(result.effect, { type: "none" })
+    assert.equal(isAtBottom(metrics(bottomOffset - BOTTOM_FOLLOW_EPSILON_PX - 0.1)), false)
+    assert.equal(isAtBottom(metrics(bottomOffset - BOTTOM_FOLLOW_EPSILON_PX)), true)
+    assert.equal(isAtBottom(metrics(bottomOffset)), true)
   })
 
-  it("blocks pre-pin upward reconciliation while restoring", () => {
-    const controller = new VirtualScrollController(true)
-    controller.recordProgrammaticOffset(2400, true)
-    controller.setRestoring(true)
+  it("treats fractional distance inside the tolerance as at-bottom", () => {
+    const bottomOffset = 2400
 
-    const result = controller.beforeBottomPin(metrics(2200))
-
-    assert.deepEqual(result.state.mode, { type: "following" })
-    assert.deepEqual(result.effect, { type: "none" })
+    assert.equal(isAtBottom(metrics(bottomOffset - BOTTOM_FOLLOW_EPSILON_PX - 0.5)), false)
+    assert.equal(isAtBottom(metrics(bottomOffset - 0.5)), true)
   })
 
-  it("distinguishes close-to-bottom from at-bottom metrics", () => {
-    const closeButNotAtBottom = metrics(2351)
-
-    assert.equal(isAtBottom(closeButNotAtBottom), false)
+  it("does not restore follow from an off-bottom snapshot", () => {
+    assert.equal(isSnapshotAutoFollowing({ atBottom: false, followModeType: "following" }), false)
+    assert.deepEqual(restoreFollowModeFromSnapshot({ atBottom: false, followModeType: "following" }), { type: "escaped" })
   })
 
-  it("excludes reasoning-only hold targets while preserving Assistant text eligibility", () => {
+  it("keeps hold element resolution as a DOM concern", () => {
     const itemWrapper = { id: "message-wrapper" } as unknown as HTMLElement
     const assistantAnswerText = { id: "assistant-answer-text" } as unknown as HTMLElement
 
@@ -383,4 +202,137 @@ describe("virtual follow behavior", () => {
     assert.equal(resolveAutoPinHoldElement(itemWrapper, "message-1", () => assistantAnswerText), assistantAnswerText)
     assert.equal(resolveAutoPinHoldElement(itemWrapper, "message-1", () => undefined), itemWrapper)
   })
+
+  it("selects the item crossing the viewport top instead of the nearest item top", () => {
+    const anchor = selectTopViewportAnchor([
+      { key: "crossing", top: -80, bottom: 120 },
+      { key: "below", top: 2, bottom: 102 },
+    ], 0, 600)
+
+    assert.equal(anchor?.key, "crossing")
+  })
+
+  it("keeps waiting for an existing anchor that mounts after six frames", () => {
+    const stabilizer = new AnchorRestoreStabilizer()
+    let result
+
+    for (let frame = 1; frame <= 7; frame += 1) {
+      result = stabilizer.nextFrame({ targetExists: true, mounted: false })
+      assert.equal(result.type, "retry")
+    }
+    for (let frame = 8; frame <= 12; frame += 1) {
+      result = stabilizer.nextFrame({ targetExists: true, mounted: false })
+    }
+
+    assert.deepEqual(result, { type: "retry", reissueIndex: true })
+  })
+
+  it("resets stable frame counting after an anchor offset correction", () => {
+    const stabilizer = new AnchorRestoreStabilizer()
+    for (let frame = 0; frame < ANCHOR_RESTORE_STABLE_FRAMES - 2; frame += 1) {
+      assert.equal(stabilizer.nextFrame({ targetExists: true, mounted: true, delta: 0.5 }).type, "retry")
+    }
+
+    assert.deepEqual(stabilizer.nextFrame({ targetExists: true, mounted: true, delta: 4 }), {
+      type: "correct",
+      delta: 4,
+      finishAfterCorrection: false,
+    })
+    assert.equal(stabilizer.snapshot().stableFrames, 0)
+    for (let frame = 0; frame < ANCHOR_RESTORE_STABLE_FRAMES - 1; frame += 1) {
+      assert.equal(stabilizer.nextFrame({ targetExists: true, mounted: true, delta: 0 }).type, "retry")
+    }
+    assert.equal(stabilizer.nextFrame({ targetExists: true, mounted: true, delta: 0 }).type, "finish")
+  })
+
+  it("restarts anchor stabilization when content grows", () => {
+    const stabilizer = new AnchorRestoreStabilizer()
+    for (let frame = 0; frame < ANCHOR_RESTORE_STABLE_FRAMES - 1; frame += 1) {
+      stabilizer.nextFrame({ targetExists: true, mounted: true, delta: 0 })
+    }
+
+    stabilizer.restartStability()
+
+    assert.equal(stabilizer.nextFrame({ targetExists: true, mounted: true, delta: 0 }).type, "retry")
+    assert.equal(stabilizer.snapshot().stableFrames, 1)
+  })
+
+  it("finishes a mounted anchor at the frame bound instead of ratio fallback", () => {
+    const stabilizer = new AnchorRestoreStabilizer()
+    let result
+    for (let frame = 1; frame <= ANCHOR_RESTORE_MAX_FRAMES; frame += 1) {
+      stabilizer.restartStability()
+      result = stabilizer.nextFrame({ targetExists: true, mounted: true, delta: 0 })
+    }
+
+    assert.deepEqual(result, { type: "finish" })
+  })
+
+  it("requests one final mounted-anchor correction at the frame bound", () => {
+    const stabilizer = new AnchorRestoreStabilizer()
+    for (let frame = 1; frame < ANCHOR_RESTORE_MAX_FRAMES; frame += 1) {
+      stabilizer.restartStability()
+      stabilizer.nextFrame({ targetExists: true, mounted: true, delta: 0 })
+    }
+
+    assert.deepEqual(stabilizer.nextFrame({ targetExists: true, mounted: true, delta: 6 }), {
+      type: "correct",
+      delta: 6,
+      finishAfterCorrection: true,
+    })
+  })
+
+  it("ratio-fallbacks at the frame bound only when an existing anchor never mounts", () => {
+    const stabilizer = new AnchorRestoreStabilizer()
+    let result
+    for (let frame = 1; frame < ANCHOR_RESTORE_MAX_FRAMES; frame += 1) {
+      result = stabilizer.nextFrame({ targetExists: true, mounted: false })
+    }
+
+    assert.equal(result?.type, "retry")
+    assert.equal(stabilizer.snapshot().elapsedFrames, ANCHOR_RESTORE_MAX_FRAMES - 1)
+    result = stabilizer.nextFrame({ targetExists: true, mounted: false })
+    assert.deepEqual(result, { type: "fallback" })
+    assert.equal(stabilizer.snapshot().elapsedFrames, ANCHOR_RESTORE_MAX_FRAMES)
+  })
+
+  it("fallbacks when a previously mounted anchor is unmounted at the strict frame bound", () => {
+    const stabilizer = new AnchorRestoreStabilizer()
+    stabilizer.nextFrame({ targetExists: true, mounted: true, delta: 4 })
+    let result
+    for (let frame = 2; frame <= ANCHOR_RESTORE_MAX_FRAMES; frame += 1) {
+      result = stabilizer.nextFrame({ targetExists: true, mounted: false })
+    }
+
+    assert.deepEqual(result, { type: "fallback" })
+    assert.equal(stabilizer.snapshot().elapsedFrames, ANCHOR_RESTORE_MAX_FRAMES)
+  })
+
+  it("invalidates deferred at-bottom and pixel-only restore finishes on cancellation", () => {
+    for (const path of ["at-bottom", "pixel-only"]) {
+      const guard = new ScrollRestoreTokenGuard()
+      const token = guard.begin()
+      let cancelled = false
+      let restoredOldMode = false
+      const finish = () => {
+        if (guard.isCurrent(token)) restoredOldMode = true
+      }
+      const cancel = () => {
+        guard.invalidate()
+        cancelled = true
+      }
+
+      cancel()
+      finish()
+
+      assert.equal(cancelled, true, path)
+      assert.equal(restoredOldMode, false, path)
+    }
+  })
+
+  it("rejects stale applied or cancellation callbacks from another session generation", () => {
+    assert.equal(isScrollRestoreGenerationCurrent("session-a", 3, "session-a", 3), true)
+    assert.equal(isScrollRestoreGenerationCurrent("session-a", 3, "session-b", 4), false)
+    assert.equal(isScrollRestoreGenerationCurrent("session-a", 3, "session-a", 4), false)
+  })
 })
diff --git a/packages/ui/src/components/virtual-follow-behavior.ts b/packages/ui/src/components/virtual-follow-behavior.ts
index ee5edbe0..3d604f44 100644
--- a/packages/ui/src/components/virtual-follow-behavior.ts
+++ b/packages/ui/src/components/virtual-follow-behavior.ts
@@ -1,24 +1,121 @@
-export type FollowMode =
-  | { type: "following" }
-  | { type: "escaped" }
-  | { type: "holding"; key: string }
+export type FollowMode = { type: "following" } | { type: "escaped" }
+
+export const BOTTOM_FOLLOW_EPSILON_PX = 48
+export const ANCHOR_RESTORE_MAX_FRAMES = 150
+export const ANCHOR_RESTORE_STABLE_FRAMES = 10
+export const ANCHOR_RESTORE_REISSUE_INTERVAL_FRAMES = 12
+export const ANCHOR_RESTORE_TOLERANCE_PX = 1
+
+export interface ViewportAnchorCandidate {
+  key: string
+  top: number
+  bottom: number
+}
+
+export type AnchorRestoreFrameResult =
+  | { type: "retry"; reissueIndex: boolean }
+  | { type: "correct"; delta: number; finishAfterCorrection: boolean }
+  | { type: "finish" }
+  | { type: "fallback" }
+
+export class ScrollRestoreTokenGuard {
+  private token = 0
+
+  begin() {
+    this.token += 1
+    return this.token
+  }
+
+  invalidate() {
+    this.token += 1
+  }
+
+  isCurrent(token: number) {
+    return token === this.token
+  }
+}
+
+export class AnchorRestoreStabilizer {
+  private elapsedFrames = 0
+  private stableFrames = 0
+
+  restartStability() {
+    this.stableFrames = 0
+  }
+
+  snapshot() {
+    return { elapsedFrames: this.elapsedFrames, stableFrames: this.stableFrames }
+  }
+
+  nextFrame(input: { targetExists: boolean; mounted: boolean; delta?: number }): AnchorRestoreFrameResult {
+    this.elapsedFrames += 1
+    if (!input.targetExists) return { type: "fallback" }
+
+    if (input.mounted && typeof input.delta === "number") {
+      if (Math.abs(input.delta) > ANCHOR_RESTORE_TOLERANCE_PX) {
+        this.stableFrames = 0
+        return {
+          type: "correct",
+          delta: input.delta,
+          finishAfterCorrection: this.elapsedFrames >= ANCHOR_RESTORE_MAX_FRAMES,
+        }
+      }
+
+      this.stableFrames += 1
+      if (this.stableFrames >= ANCHOR_RESTORE_STABLE_FRAMES || this.elapsedFrames >= ANCHOR_RESTORE_MAX_FRAMES) {
+        return { type: "finish" }
+      }
+    } else {
+      this.stableFrames = 0
+    }
+
+    if (this.elapsedFrames >= ANCHOR_RESTORE_MAX_FRAMES && input.mounted) return { type: "finish" }
+    if (this.elapsedFrames >= ANCHOR_RESTORE_MAX_FRAMES) return { type: "fallback" }
+    return {
+      type: "retry",
+      reissueIndex: !input.mounted && this.elapsedFrames % ANCHOR_RESTORE_REISSUE_INTERVAL_FRAMES === 0,
+    }
+  }
+}
+
+export function selectTopViewportAnchor(
+  candidates: ViewportAnchorCandidate[],
+  viewportTop: number,
+  viewportBottom: number,
+  preferredKey?: string,
+) {
+  const visible = candidates.filter((candidate) => candidate.bottom > viewportTop && candidate.top < viewportBottom)
+  const crossingTop = visible
+    .filter((candidate) => candidate.top <= viewportTop && candidate.bottom > viewportTop)
+    .sort((a, b) => b.top - a.top)[0]
+  if (crossingTop) return crossingTop
+
+  const preferred = preferredKey ? visible.find((candidate) => candidate.key === preferredKey) : undefined
+  if (preferred) return preferred
+  return visible.sort((a, b) => a.top - b.top)[0]
+}
+
+export function isScrollRestoreGenerationCurrent(
+  startedSessionId: string,
+  startedGeneration: number,
+  currentSessionId: string,
+  currentGeneration: number,
+) {
+  return startedSessionId === currentSessionId && startedGeneration === currentGeneration
+}
 
 export type FollowEffect =
   | { type: "none" }
   | { type: "scroll-top"; immediate: boolean }
-  | { type: "scroll-bottom"; immediate: boolean; suppressHold: boolean }
+  | { type: "scroll-bottom"; immediate: boolean }
   | { type: "scroll-key"; key: string; block: ScrollLogicalPosition; smooth: boolean }
-  | { type: "align-hold"; key: string }
 
 export type FollowEvent =
-  | { type: "user-scroll"; direction: "up" | "down" | null; atBottom: boolean; canPinToBottom: boolean }
+  | { type: "user-scroll"; direction: "up" | "down" | null; atBottom: boolean }
   | { type: "jump-top"; immediate: boolean }
   | { type: "jump-bottom"; immediate: boolean; explicit: boolean }
-  | { type: "jump-key"; key: string; block: ScrollLogicalPosition; smooth: boolean; followAfter: boolean }
+  | { type: "jump-key"; key: string; block: ScrollLogicalPosition; smooth: boolean }
   | { type: "content-grew"; canPinToBottom: boolean }
-  | { type: "hold-candidate"; key: string; shouldHold: boolean }
-  | { type: "hold-target-changed"; key: string | null; canPinToBottom: boolean }
-  | { type: "clear-hold"; follow: boolean; canPinToBottom: boolean; suppressHold: boolean }
   | { type: "set-follow"; enabled: boolean }
   | { type: "reset"; follow: boolean }
 
@@ -61,8 +158,6 @@ export interface ScrollControllerSnapshot {
 
 export interface FollowSnapshotState {
   followModeType?: FollowMode["type"]
-  heldKey?: string
-  holdAnchorSuspended?: boolean
 }
 
 export type HoldTargetElementResolver = (itemWrapper: HTMLElement, key: string) => HTMLElement | null | undefined
@@ -73,10 +168,6 @@ export function isAutoFollowing(mode: FollowMode) {
   return mode.type === "following"
 }
 
-export function getHeldKey(mode: FollowMode) {
-  return mode.type === "holding" ? mode.key : null
-}
-
 export function resolveAutoPinHoldElement(
   itemWrapper: HTMLElement | null | undefined,
   key: string,
@@ -89,79 +180,25 @@ export function resolveAutoPinHoldElement(
   return resolved === undefined ? itemWrapper : resolved
 }
 
-export function shouldSuspendAutoPinToBottomForHold(state: {
-  externalSuspend: boolean
-  activeHoldTargetKey: string | null
-  eligibleHoldTargetKey?: string | null
-}) {
-  return state.externalSuspend || state.activeHoldTargetKey !== null
-}
-
-export function shouldTrackHeldAnchor(state: {
-  activeHoldTargetKey: string | null
-  eligibleHoldTargetKey: string | null
-  suspendedByUser: boolean
-}) {
-  return !state.suspendedByUser && state.activeHoldTargetKey !== null && state.activeHoldTargetKey === state.eligibleHoldTargetKey
-}
-
 export function isSnapshotAutoFollowing(snapshot: { atBottom: boolean; followModeType?: FollowMode["type"] } | null | undefined) {
   if (!snapshot) return true
-  if (snapshot.followModeType) return snapshot.followModeType === "following"
-  return snapshot.atBottom
+  return snapshot.atBottom && snapshot.followModeType !== "escaped"
 }
 
-export function getFollowSnapshotState(mode: FollowMode, holdAnchorSuspended: boolean): FollowSnapshotState {
-  if (mode.type === "holding") {
-    return {
-      followModeType: "holding",
-      heldKey: mode.key,
-      holdAnchorSuspended: holdAnchorSuspended || undefined,
-    }
-  }
-
+export function getFollowSnapshotState(mode: FollowMode): FollowSnapshotState {
   return { followModeType: mode.type }
 }
 
-export function restoreFollowModeFromSnapshot(state: {
-  atBottom: boolean
-  followModeType?: FollowMode["type"]
-  heldKey?: string
-  hasHeldKeyItem?: boolean
-}): FollowMode {
-  if (state.followModeType === "holding" && state.heldKey && state.hasHeldKeyItem) {
-    return { type: "holding", key: state.heldKey }
-  }
-  if (state.followModeType === "following") {
-    return { type: "following" }
-  }
-  if (state.followModeType === "escaped") {
-    return { type: "escaped" }
-  }
+export function restoreFollowModeFromSnapshot(state: { atBottom: boolean; followModeType?: FollowMode["type"] }): FollowMode {
+  if (state.followModeType === "escaped") return { type: "escaped" }
   return state.atBottom ? { type: "following" } : { type: "escaped" }
 }
 
 export function transitionFollowMode(mode: FollowMode, event: FollowEvent): FollowTransition {
   switch (event.type) {
     case "user-scroll": {
-      if (mode.type === "holding") {
-        if (event.atBottom && event.direction !== "up") {
-          return { mode: { type: "following" }, effect: noFollowEffect }
-        }
-        return { mode, effect: noFollowEffect }
-      }
-      if (event.direction === "up") {
-        return { mode: { type: "escaped" }, effect: noFollowEffect }
-      }
-      if (mode.type === "escaped" && event.direction === "down" && event.atBottom && event.canPinToBottom) {
-        return {
-          mode: { type: "following" },
-          effect: { type: "scroll-bottom", immediate: true, suppressHold: false },
-        }
-      }
-      if (event.atBottom) {
-        return { mode: { type: "following" }, effect: noFollowEffect }
-      }
+      if (event.direction === "up") return { mode: { type: "escaped" }, effect: noFollowEffect }
+      if (event.atBottom) return { mode: { type: "following" }, effect: noFollowEffect }
       return { mode, effect: noFollowEffect }
     }
 
@@ -171,42 +208,21 @@ export function transitionFollowMode(mode: FollowMode, event: FollowEvent): Foll
     case "jump-bottom":
       return {
         mode: { type: "following" },
-        effect: { type: "scroll-bottom", immediate: event.immediate, suppressHold: event.explicit },
+        effect: { type: "scroll-bottom", immediate: event.immediate },
       }
 
     case "jump-key":
       return {
-        mode: event.followAfter ? { type: "following" } : { type: "escaped" },
+        mode: { type: "escaped" },
         effect: { type: "scroll-key", key: event.key, block: event.block, smooth: event.smooth },
       }
 
     case "content-grew":
       if (mode.type === "following" && event.canPinToBottom) {
-        return { mode, effect: { type: "scroll-bottom", immediate: true, suppressHold: false } }
+        return { mode, effect: { type: "scroll-bottom", immediate: true } }
       }
       return { mode, effect: noFollowEffect }
 
-    case "hold-candidate":
-      if (mode.type === "following" && event.shouldHold) {
-        return { mode: { type: "holding", key: event.key }, effect: { type: "align-hold", key: event.key } }
-      }
-      return { mode, effect: noFollowEffect }
-
-    case "hold-target-changed":
-      return { mode, effect: noFollowEffect }
-
-    case "clear-hold":
-      if (mode.type !== "holding") {
-        return { mode, effect: noFollowEffect }
-      }
-      return {
-        mode: event.follow ? { type: "following" } : { type: "escaped" },
-        effect:
-          event.follow && event.canPinToBottom
-            ? { type: "scroll-bottom", immediate: true, suppressHold: event.suppressHold }
-            : noFollowEffect,
-      }
-
     case "set-follow":
       return { mode: event.enabled ? { type: "following" } : { type: "escaped" }, effect: noFollowEffect }
 
@@ -245,10 +261,6 @@ export class VirtualScrollController {
     return isAutoFollowing(this.state.mode)
   }
 
-  heldKey() {
-    return this.state.mode.type === "holding" ? this.state.mode.key : null
-  }
-
   setUserIntent(direction: ScrollDirection, until: number) {
     this.state.userIntentDirection = direction
     this.state.userIntentUntil = until
@@ -293,42 +305,22 @@ export class VirtualScrollController {
   }
 
   jumpBottom(immediate: boolean, explicit: boolean): ScrollControllerResult {
+    if (explicit) {
+      this.state.userIntentDirection = null
+      this.state.userIntentUntil = 0
+    }
     const next = transitionFollowMode(this.state.mode, { type: "jump-bottom", immediate, explicit })
     this.state.mode = next.mode
     return this.result(next.effect)
   }
 
-  jumpKey(key: string, block: ScrollLogicalPosition, smooth: boolean, followAfter: boolean): ScrollControllerResult {
-    const next = transitionFollowMode(this.state.mode, { type: "jump-key", key, block, smooth, followAfter })
+  jumpKey(key: string, block: ScrollLogicalPosition, smooth: boolean): ScrollControllerResult {
+    const next = transitionFollowMode(this.state.mode, { type: "jump-key", key, block, smooth })
     this.state.mode = next.mode
     return this.result(next.effect)
   }
 
-  holdCandidate(key: string, shouldHold: boolean): ScrollControllerResult {
-    const next = transitionFollowMode(this.state.mode, { type: "hold-candidate", key, shouldHold })
-    this.state.mode = next.mode
-    return this.result(next.effect)
-  }
-
-  holdTargetChanged(key: string | null, canPinToBottom: boolean): ScrollControllerResult {
-    const next = transitionFollowMode(this.state.mode, { type: "hold-target-changed", key, canPinToBottom })
-    this.state.mode = next.mode
-    return this.result(next.effect)
-  }
-
-  clearHold(follow: boolean, canPinToBottom: boolean, suppressHold: boolean): ScrollControllerResult {
-    const next = transitionFollowMode(this.state.mode, { type: "clear-hold", follow, canPinToBottom, suppressHold })
-    this.state.mode = next.mode
-    return this.result(next.effect)
-  }
-
-  observeViewport(
-    metrics: ScrollControllerMetrics,
-    now: number,
-    programmatic: boolean,
-    canPinToBottom = false,
-    forceEscapeFromUpScroll = false,
-  ): ScrollControllerResult {
+  observeViewport(metrics: ScrollControllerMetrics, now: number, programmatic: boolean): ScrollControllerResult {
     const previousOffset = this.state.lastObservedOffset
     const offset = metrics.offset
     const scrolledUp = offset < previousOffset - 1
@@ -340,66 +332,39 @@ export class VirtualScrollController {
     this.clearExpiredUserIntent(now)
 
     const hasFreshIntent = now <= this.state.userIntentUntil
-    if (
-      scrolledUp &&
-      this.isAutoFollowing() &&
-      (forceEscapeFromUpScroll || !atBottom) &&
-      this.heldKey() === null &&
-      (!programmatic || hasFreshIntent)
-    ) {
+    const actualDirection: ScrollDirection = scrolledUp ? "up" : scrolledDown ? "down" : null
+    if (hasFreshIntent && this.state.userIntentDirection === "up") {
       return this.setFollow(false)
     }
 
-    const actualDirection: ScrollDirection = scrolledUp ? "up" : scrolledDown ? "down" : null
+    const direction = actualDirection ?? this.state.userIntentDirection
+
     if (!hasFreshIntent && (!actualDirection || programmatic)) {
       return this.result(noFollowEffect)
     }
 
-    const direction = actualDirection ?? this.state.userIntentDirection
-    const canMagnetToBottom = hasFreshIntent && direction === "down" && canPinToBottom
-    const next = transitionFollowMode(this.state.mode, {
-      type: "user-scroll",
-      direction,
-      atBottom,
-      canPinToBottom: canMagnetToBottom,
-    })
+    if (direction === "up" && (!programmatic || hasFreshIntent)) {
+      return this.setFollow(false)
+    }
+
+    const next = transitionFollowMode(this.state.mode, { type: "user-scroll", direction, atBottom })
     this.state.mode = next.mode
     this.state.lastObservedAtBottom = this.isAutoFollowing() && atBottom
     return this.result(next.effect)
   }
 
-  contentRendered(metrics: ScrollControllerMetrics, canPinToBottom: boolean): ScrollControllerResult {
+  contentRendered(_metrics: ScrollControllerMetrics, canPinToBottom: boolean): ScrollControllerResult {
     if (this.state.restoring) return this.result(noFollowEffect)
-    if (!canPinToBottom || !this.isAutoFollowing()) {
-      const reconcile = this.reconcileUpwardDomMovement(metrics)
-      if (reconcile.effect.type !== "none") return reconcile
-    }
-
     const next = transitionFollowMode(this.state.mode, { type: "content-grew", canPinToBottom })
     this.state.mode = next.mode
     return this.result(next.effect)
   }
 
-  beforeBottomPin(metrics: ScrollControllerMetrics): ScrollControllerResult {
-    if (this.state.restoring) return this.result(noFollowEffect)
-    return this.reconcileUpwardDomMovement(metrics)
-  }
-
   recordProgrammaticOffset(offset: number, atBottom: boolean) {
     this.state.lastObservedOffset = offset
     this.state.lastObservedAtBottom = this.isAutoFollowing() && atBottom
   }
 
-  private reconcileUpwardDomMovement(metrics: ScrollControllerMetrics): ScrollControllerResult {
-    if (!this.isAutoFollowing()) return this.result(noFollowEffect)
-    if (this.heldKey() !== null) return this.result(noFollowEffect)
-    if (isAtBottom(metrics)) return this.result(noFollowEffect)
-    if (metrics.offset >= this.state.lastObservedOffset - 1) return this.result(noFollowEffect)
-    this.state.lastObservedOffset = metrics.offset
-    this.state.lastObservedAtBottom = false
-    return this.setFollow(false)
-  }
-
   private result(effect: FollowEffect): ScrollControllerResult {
     return { effect, state: this.snapshot() }
   }
diff --git a/packages/ui/src/components/virtual-follow-list.tsx b/packages/ui/src/components/virtual-follow-list.tsx
index 0b3cf440..8a7f17ad 100644
--- a/packages/ui/src/components/virtual-follow-list.tsx
+++ b/packages/ui/src/components/virtual-follow-list.tsx
@@ -1,26 +1,27 @@
 import { Show, createEffect, createMemo, createSignal, type Accessor, type JSX, on, onCleanup } from "solid-js"
 import { Virtualizer, type VirtualizerHandle } from "virtua/solid"
-import { getFollowSnapshotState, getHeldKey, isAutoFollowing, isAtBottom, resolveAutoPinHoldElement, restoreFollowModeFromSnapshot, shouldSuspendAutoPinToBottomForHold, shouldTrackHeldAnchor, VirtualScrollController, type FollowEffect, type FollowEvent, type FollowMode, type HoldTargetElementResolver, type ScrollControllerMetrics, type ScrollControllerResult } from "./virtual-follow-behavior.ts"
+import { AnchorRestoreStabilizer, BOTTOM_FOLLOW_EPSILON_PX, getFollowSnapshotState, isAtBottom, isAutoFollowing, resolveAutoPinHoldElement, restoreFollowModeFromSnapshot, ScrollRestoreTokenGuard, selectTopViewportAnchor, VirtualScrollController, type FollowEffect, type FollowEvent, type FollowMode, type HoldTargetElementResolver, type ScrollControllerMetrics, type ScrollControllerResult } from "./virtual-follow-behavior.ts"
 
-const DEFAULT_SCROLL_SENTINEL_MARGIN_PX = 48
 const DEFAULT_HOLD_TARGET_TOP_THRESHOLD_PX = 8
+const EXPLICIT_BOTTOM_PIN_SETTLE_FRAMES = 2
+const TOP_SCROLL_EPSILON_PX = 0
+const EXPLICIT_BOTTOM_PIN_MAX_FRAMES = 90
 const USER_SCROLL_INTENT_WINDOW_MS = 600
-const BOTTOM_FOLLOW_INTENT_SETTLE_FRAMES = 4
-const BOTTOM_FOLLOW_INTENT_MAX_FRAMES = 60
+const PROGRAMMATIC_SCROLL_WINDOW_MS = 120
 const SCROLL_INTENT_KEYS = new Set(["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " ", "Spacebar"])
 const INTERACTIVE_KEY_TARGET_SELECTOR = "button, a, input, textarea, select, [contenteditable='true'], [role='button'], [role='textbox']"
 
-export interface VirtualFollowBottomIntent {
+export interface VirtualExplicitBottomPinIntent {
   token: string | number
   minItemCount?: number
 }
 
 export interface VirtualFollowListApi {
   scrollToTop: (opts?: { immediate?: boolean }) => void
-  scrollToBottom: (opts?: { immediate?: boolean; suppressAutoAnchor?: boolean; suppressHold?: boolean }) => void
+  scrollToBottom: (opts?: { immediate?: boolean }) => void
   scrollToKey: (
     key: string,
-    opts?: { behavior?: ScrollBehavior; block?: ScrollLogicalPosition; setAutoScroll?: boolean },
+    opts?: { behavior?: ScrollBehavior; block?: ScrollLogicalPosition },
   ) => void
   notifyContentRendered: () => void
   setAutoScroll: (enabled: boolean) => void
@@ -39,14 +40,13 @@ export interface VirtualFollowScrollSnapshot {
   anchorOffset?: number
   atBottom: boolean
   followModeType?: FollowMode["type"]
-  heldKey?: string
-  holdAnchorSuspended?: boolean
 }
 
 interface RestoreScrollSnapshotOptions {
   behavior?: ScrollBehavior
   fallback?: () => void
   onApplied?: () => void
+  onCancelled?: () => void
 }
 
 export interface VirtualFollowListState {
@@ -61,112 +61,29 @@ export interface VirtualFollowListProps<T> {
   items: Accessor<T[]>
   getKey: (item: T, index: number) => string
   renderItem: (item: T, index: number) => JSX.Element
-
-  /**
-   * Optional stable DOM id for the item wrapper.
-   * Defaults to the key itself.
-   */
   getAnchorId?: (key: string) => string
-
   overscanPx?: number
-  scrollSentinelMarginPx?: number
-  virtualizationEnabled?: Accessor<boolean>
-  suspendMeasurements?: Accessor<boolean>
   streamingActive?: Accessor<boolean>
   isActive?: Accessor<boolean>
   autoPinHoldEnabled?: Accessor<boolean>
-
-  /**
-   * When switching back to an inactive (cached) pane, the list historically
-   * re-pinned to the bottom if autoScroll was enabled.
-   *
-   * Disable this to preserve the existing scroll position across pane switches.
-   */
   scrollToBottomOnActivate?: Accessor<boolean>
-
-  /**
-   * Controls whether the list should scroll to bottom the first time items
-   * appear (default behavior for chat streams).
-   *
-   * Set to false when an outer component restores scroll from a cache.
-   */
   initialScrollToBottom?: Accessor<boolean>
-
-  /**
-   * Initial value for the internal autoScroll signal.
-   * Useful when restoring scroll state (e.g. start in non-follow mode).
-   */
   initialAutoScroll?: Accessor<boolean>
-
-  /**
-   * When this value changes, the list resets internal follow/anchor state.
-   * Useful when reusing the same list instance across different datasets.
-   */
   resetKey?: Accessor<string | number>
-
-  /**
-   * If this value changes and autoScroll is enabled, the list will
-   * anchor-scroll to the bottom (unless suppressed).
-   */
   followToken?: Accessor<string | number>
-
-  /**
-   * Explicit submit intent that temporarily overrides stale hold/restore state
-   * until the newly submitted exchange has mounted.
-   */
-  forceBottomFollowIntent?: Accessor<VirtualFollowBottomIntent | null>
-
-  /**
-   * Optional item key whose geometry can temporarily hold auto-follow when the
-   * rendered item grows taller than the viewport and reaches the top edge.
-   */
+  explicitBottomPinIntent?: Accessor<VirtualExplicitBottomPinIntent | null>
   autoPinHoldTargetKey?: Accessor<string | null>
-
-  /**
-   * Optional resolver for the specific element inside an item wrapper that
-   * should be measured for hold-target geometry. Return null when the item has
-   * no eligible hold target; return undefined to fall back to the item wrapper.
-   */
   resolveAutoPinHoldElement?: HoldTargetElementResolver
-
-  /**
-   * Top-edge threshold for the hold target in pixels.
-   */
   autoPinHoldTopThresholdPx?: number
-
-  /**
-   * Temporarily suppress automatic bottom pinning while keeping follow mode enabled.
-   */
   suspendAutoPinToBottom?: Accessor<boolean>
-
-  /**
-   * Optional hooks to render content inside the scroll container.
-   * Useful for empty/loading states that should scroll with the list.
-   */
   renderBeforeItems?: Accessor<JSX.Element>
-
-  /**
-   * Render content inside the shell, above timeline/sidebar layers.
-   * (Quote popovers, etc.)
-   */
   renderOverlay?: Accessor<JSX.Element>
-
-  /**
-   * Provide localized labels for built-in controls.
-   */
   scrollToTopAriaLabel?: Accessor<string>
   scrollToBottomAriaLabel?: Accessor<string>
-
-  /**
-   * Receive element refs for external logic (selection, geometry, etc.)
-   */
   onScrollElementChange?: (element: HTMLDivElement | undefined) => void
   onShellElementChange?: (element: HTMLDivElement | undefined) => void
-
-  /**
-   * Callbacks for consumers.
-   */
   onScroll?: () => void
+  onExplicitBottomPinCancelled?: () => void
   onMouseUp?: (event: MouseEvent) => void
   onClick?: (event: MouseEvent) => void
   onActiveKeyChange?: (key: string | null) => void
@@ -179,363 +96,138 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
   const [scrollElement, setScrollElement] = createSignal<HTMLDivElement | undefined>()
   const [shellElement, setShellElement] = createSignal<HTMLDivElement | undefined>()
   const [virtuaHandle, setVirtuaHandle] = createSignal<VirtualizerHandle | undefined>()
-
-  const isActive = () => (props.isActive ? props.isActive() : true)
-  const scrollToBottomOnActivate = () => (props.scrollToBottomOnActivate ? props.scrollToBottomOnActivate() : true)
-  const initialScrollToBottom = () => (props.initialScrollToBottom ? props.initialScrollToBottom() : true)
-  const initialAutoScroll = () => (props.initialAutoScroll ? props.initialAutoScroll() : true)
-  const externalSuspendAutoPinToBottom = () => (props.suspendAutoPinToBottom ? props.suspendAutoPinToBottom() : false)
-  const streamingActive = () => props.streamingActive?.() ?? false
-  const autoPinHoldEnabled = () => props.autoPinHoldEnabled?.() ?? true
-  const holdTargetKey = () => (props.autoPinHoldTargetKey ? props.autoPinHoldTargetKey() : null)
-  const forceBottomFollowIntent = () => props.forceBottomFollowIntent?.() ?? null
-  const holdTargetTopThresholdPx = () => props.autoPinHoldTopThresholdPx ?? DEFAULT_HOLD_TARGET_TOP_THRESHOLD_PX
-
-  const scrollController = new VirtualScrollController(initialAutoScroll())
-  const [followMode, setFollowMode] = createSignal<FollowMode>(scrollController.snapshot().mode)
-  const autoScroll = createMemo(() => isAutoFollowing(followMode()))
+  const [followMode, setFollowMode] = createSignal<FollowMode>({ type: props.initialAutoScroll?.() ?? true ? "following" : "escaped" })
   const [showScrollTopButton, setShowScrollTopButton] = createSignal(false)
   const [showScrollBottomButton, setShowScrollBottomButton] = createSignal(false)
   const [activeKey, setActiveKey] = createSignal<string | null>(null)
-  const activeHoldTargetKey = createMemo(() => getHeldKey(followMode()))
-  const [didTriggerHoldForCurrentTarget, setDidTriggerHoldForCurrentTarget] = createSignal(false)
-  const effectiveSuspendAutoPinToBottom = () => shouldSuspendAutoPinToBottomForHold({
-    externalSuspend: externalSuspendAutoPinToBottom(),
-    activeHoldTargetKey: activeHoldTargetKey(),
-    eligibleHoldTargetKey: holdTargetKey(),
-  })
 
+  const isActive = () => props.isActive?.() ?? true
+  const initialScrollToBottom = () => props.initialScrollToBottom?.() ?? true
+  const initialAutoScroll = () => props.initialAutoScroll?.() ?? true
+  const scrollToBottomOnActivate = () => props.scrollToBottomOnActivate?.() ?? true
+  const streamingActive = () => props.streamingActive?.() ?? false
+  const autoPinHoldEnabled = () => props.autoPinHoldEnabled?.() ?? true
+  const holdTargetKey = () => props.autoPinHoldTargetKey?.() ?? null
+  const externalSuspendAutoPinToBottom = () => props.suspendAutoPinToBottom?.() ?? false
+  const explicitBottomPinIntent = () => props.explicitBottomPinIntent?.() ?? null
+  const holdTargetTopThresholdPx = () => props.autoPinHoldTopThresholdPx ?? DEFAULT_HOLD_TARGET_TOP_THRESHOLD_PX
+  const autoScroll = createMemo(() => isAutoFollowing(followMode()))
   const scrollButtonsCount = createMemo(() => (showScrollTopButton() ? 1 : 0) + (showScrollBottomButton() ? 1 : 0))
+
+  const scrollController = new VirtualScrollController(initialAutoScroll())
   const itemElements = new Map<string, HTMLDivElement>()
+  const state: VirtualFollowListState = { autoScroll, showScrollTopButton, showScrollBottomButton, scrollButtonsCount, activeKey }
 
   let detachScrollIntentListeners: (() => void) | undefined
-  let lastResetKey: string | number | undefined
-  let suppressAutoScrollOnce = false
-  let suppressHoldUntilTargetChanges = false
-  let suspendHeldAnchorUntilBottom = false
-  let lastItemsReference = props.items()
-  let restoreToken = 0
-
-  createEffect(() => {
-    const items = props.items()
-    if (items === lastItemsReference) return
-    lastItemsReference = items
-    restoreToken += 1
-    scrollController.setRestoring(false)
-  })
-
-  onCleanup(() => {
-    restoreToken += 1
-    scrollController.setRestoring(false)
-  })
+  const restoreToken = new ScrollRestoreTokenGuard()
+  let restartAnchorRestore: (() => void) | undefined
+  let cancelRestore: (() => void) | undefined
+  let lastResetKey: string | number | undefined = props.resetKey?.()
   let pendingInitialScroll = true
-  let programmaticScrollUntil = 0
-  let pendingBottomRepinAfterHold = false
   let pendingContentRenderedFrame: number | null = null
-  let pendingBottomFollowIntentFrame: number | null = null
-  let bottomFollowIntentToken: string | number | null = null
-  let bottomFollowIntentMinItemCount = 0
-  let bottomFollowIntentStaleHoldTargetKey: string | null = null
-  let bottomFollowIntentSettleFrames = 0
-  let bottomFollowIntentFramesRemaining = 0
-  let heldAnchorKey: string | null = null
-  let heldAnchorElement: HTMLElement | null = null
-  let heldAnchorOffset: number | null = null
+  let pendingExplicitBottomPinFrame: number | null = null
+  let explicitBottomPinToken: string | number | null = null
+  let userCancelledExplicitBottomPinToken: string | number | null = null
+  let explicitBottomPinMinItemCount = 0
+  let explicitBottomPinSettleFrames = 0
+  let explicitBottomPinFramesRemaining = 0
+  let programmaticScrollUntil = 0
 
-  const state: VirtualFollowListState = {
-    autoScroll,
-    showScrollTopButton,
-    showScrollBottomButton,
-    scrollButtonsCount,
-    activeKey,
-  }
-
-  function markUserScrollIntent(direction?: "up" | "down" | null) {
-    if (hasActiveBottomFollowIntent()) {
-      clearBottomFollowIntent()
-    }
-    const now = performance.now()
-    scrollController.setUserIntent(direction ?? null, now + USER_SCROLL_INTENT_WINDOW_MS)
-  }
-
-  function markProgrammaticScroll() {
-    programmaticScrollUntil = performance.now() + 120
-  }
-
-  function hasProgrammaticScrollIntent() {
-    return performance.now() <= programmaticScrollUntil
-  }
-
-  function hasActiveBottomFollowIntent() {
-    return bottomFollowIntentToken !== null
-  }
-
-  function resetStaleHoldForBottomIntent() {
-    restoreToken += 1
+  function invalidateScrollRestore() {
+    restoreToken.invalidate()
+    restartAnchorRestore = undefined
+    cancelRestore = undefined
     scrollController.setRestoring(false)
-    setDidTriggerHoldForCurrentTarget(false)
-    suppressHoldUntilTargetChanges = true
-    pendingBottomRepinAfterHold = false
-    clearHeldAnchor()
   }
 
-  function clearBottomFollowIntent() {
-    const staleTargetStillCurrent = bottomFollowIntentStaleHoldTargetKey !== null && holdTargetKey() === bottomFollowIntentStaleHoldTargetKey
-    bottomFollowIntentToken = null
-    bottomFollowIntentMinItemCount = 0
-    bottomFollowIntentStaleHoldTargetKey = null
-    bottomFollowIntentSettleFrames = 0
-    bottomFollowIntentFramesRemaining = 0
-    if (!staleTargetStillCurrent) {
-      suppressHoldUntilTargetChanges = false
-    }
-  }
-
-  function scheduleBottomFollowIntentFrame() {
-    if (!hasActiveBottomFollowIntent()) return
-    if (pendingBottomFollowIntentFrame !== null) return
-    if (typeof requestAnimationFrame !== "function") {
-      runBottomFollowIntentFrame()
-      return
-    }
-    pendingBottomFollowIntentFrame = requestAnimationFrame(() => runBottomFollowIntentFrame())
-  }
-
-  function runBottomFollowIntentFrame() {
-    pendingBottomFollowIntentFrame = null
-    if (!hasActiveBottomFollowIntent()) return
-
-    resetStaleHoldForBottomIntent()
-    dispatchFollowEvent({ type: "jump-bottom", immediate: true, explicit: true })
-
-    const minItemCountReached = props.items().length >= bottomFollowIntentMinItemCount
-    if (minItemCountReached) {
-      bottomFollowIntentSettleFrames -= 1
-    } else {
-      bottomFollowIntentSettleFrames = BOTTOM_FOLLOW_INTENT_SETTLE_FRAMES
-    }
-    bottomFollowIntentFramesRemaining -= 1
-
-    if ((minItemCountReached && bottomFollowIntentSettleFrames <= 0) || bottomFollowIntentFramesRemaining <= 0) {
-      clearBottomFollowIntent()
-      return
-    }
-
-    scheduleBottomFollowIntentFrame()
-  }
-
-  function startBottomFollowIntent(intent: VirtualFollowBottomIntent | null) {
-    if (!intent) return
-    if (!hasActiveBottomFollowIntent()) {
-      bottomFollowIntentStaleHoldTargetKey = activeHoldTargetKey() ?? holdTargetKey()
-    }
-    bottomFollowIntentToken = intent.token
-    bottomFollowIntentMinItemCount = Math.max(0, Math.floor(intent.minItemCount ?? 0))
-    bottomFollowIntentSettleFrames = BOTTOM_FOLLOW_INTENT_SETTLE_FRAMES
-    bottomFollowIntentFramesRemaining = BOTTOM_FOLLOW_INTENT_MAX_FRAMES
-    resetStaleHoldForBottomIntent()
-    runBottomFollowIntentFrame()
-  }
-
-  function shouldManageHeldAnchor(key = activeHoldTargetKey(), targetKey = holdTargetKey()) {
-    if (key === null || key !== activeHoldTargetKey()) return false
-    return shouldTrackHeldAnchor({
-      activeHoldTargetKey: key,
-      eligibleHoldTargetKey: targetKey,
-      suspendedByUser: suspendHeldAnchorUntilBottom,
-    })
-  }
-
-  function hasItemKey(key: string) {
-    return props.items().some((item, index) => props.getKey(item, index) === key)
-  }
-
-  function applyRestoredFollowSnapshot(snapshot: VirtualFollowScrollSnapshot) {
-    const restoredMode = restoreFollowModeFromSnapshot({
-      atBottom: snapshot.atBottom,
-      followModeType: snapshot.followModeType,
-      heldKey: snapshot.heldKey,
-      hasHeldKeyItem: snapshot.heldKey ? hasItemKey(snapshot.heldKey) : false,
-    })
-
-    suspendHeldAnchorUntilBottom = restoredMode.type === "holding" && Boolean(snapshot.holdAnchorSuspended)
-    setFollowMode(restoredMode)
-    scrollController.restoreMode(restoredMode)
-
-    if (restoredMode.type === "holding" && shouldManageHeldAnchor(restoredMode.key)) {
-      captureHeldAnchor(restoredMode.key)
-      return
-    }
-
-    clearHeldAnchor()
+  function cancelActiveScrollRestore() {
+    const onCancelled = cancelRestore
+    if (!onCancelled) return
+    invalidateScrollRestore()
+    onCancelled()
   }
 
   function syncControllerResult(result: ScrollControllerResult) {
-    const previousMode = followMode()
-    const previousHeldKey = previousMode.type === "holding" ? previousMode.key : null
     setFollowMode(result.state.mode)
-    if (result.state.mode.type !== "holding") {
-      suspendHeldAnchorUntilBottom = false
-      clearHeldAnchor()
-    } else if (previousHeldKey !== result.state.mode.key) {
-      suspendHeldAnchorUntilBottom = false
-      clearHeldAnchor()
-    } else if (heldAnchorKey !== null && heldAnchorKey !== result.state.mode.key) {
-      clearHeldAnchor()
-    }
     applyFollowEffect(result.effect)
   }
 
-  function escapeFollowIfDomMovedUp(element = scrollElement()) {
-    if (!element) return false
-    const result = scrollController.beforeBottomPin(getDomMetrics(element))
-    syncControllerResult(result)
-    return result.effect.type !== "none" || result.state.mode.type === "escaped"
-  }
-
-  function shouldHonorPrePinEscape() {
-    const snapshot = scrollController.snapshot()
-    return performance.now() <= snapshot.userIntentUntil && snapshot.userIntentDirection === "up"
-  }
-
   function dispatchFollowEvent(event: FollowEvent) {
-    let result: ScrollControllerResult
     switch (event.type) {
-      case "user-scroll": {
-        const metrics = getManualMetrics(event.atBottom)
-        result = scrollController.observeViewport(
-          metrics,
-          performance.now(),
-          hasProgrammaticScrollIntent(),
-          canRejoinFollowFromDownScroll(metrics),
-          autoPinHoldEnabled() && streamingActive(),
-        )
-        break
-      }
-      case "jump-top":
-        result = scrollController.jumpTop(event.immediate)
-        break
-      case "jump-bottom":
-        result = scrollController.jumpBottom(event.immediate, event.explicit)
-        break
-      case "jump-key":
-        result = scrollController.jumpKey(event.key, event.block, event.smooth, event.followAfter)
-        break
-      case "content-grew": {
-        const element = scrollElement()
-        result = element
-          ? scrollController.contentRendered(getDomMetrics(element), event.canPinToBottom)
-          : scrollController.contentRendered(getManualMetrics(false), event.canPinToBottom)
-        break
-      }
-      case "hold-candidate":
-        result = scrollController.holdCandidate(event.key, event.shouldHold)
-        break
-      case "hold-target-changed":
-        result = scrollController.holdTargetChanged(event.key, event.canPinToBottom)
-        break
-      case "clear-hold":
-        result = scrollController.clearHold(event.follow, event.canPinToBottom, event.suppressHold)
-        break
-      case "set-follow":
-        result = scrollController.setFollow(event.enabled)
-        break
-      case "reset":
-        result = scrollController.reset(event.follow)
-        break
+      case "user-scroll": return syncControllerResult(scrollController.observeViewport(getManualMetrics(event.atBottom), performance.now(), hasProgrammaticScrollIntent()))
+      case "jump-top": return syncControllerResult(scrollController.jumpTop(event.immediate))
+      case "jump-bottom": return syncControllerResult(scrollController.jumpBottom(event.immediate, event.explicit))
+      case "jump-key": return syncControllerResult(scrollController.jumpKey(event.key, event.block, event.smooth))
+      case "content-grew": return syncControllerResult(scrollController.contentRendered(getCurrentMetrics(), event.canPinToBottom))
+      case "set-follow": return syncControllerResult(scrollController.setFollow(event.enabled))
+      case "reset": return syncControllerResult(scrollController.reset(event.follow))
     }
-    syncControllerResult(result)
   }
 
   function applyFollowEffect(effect: FollowEffect) {
     switch (effect.type) {
       case "none":
         return
-      case "scroll-top":
-        performScrollToTop(effect.immediate)
-        return
-      case "scroll-bottom":
-        if (effect.suppressHold) {
-          suppressHoldUntilTargetChanges = true
-        }
-        performScrollToBottom(effect.immediate)
-        return
-      case "scroll-key":
-        performScrollToKey(effect.key, { block: effect.block, smooth: effect.smooth })
-        return
-      case "align-hold":
-        alignHoldTarget(effect.key)
-        return
+      case "scroll-top": return performScrollToTop(effect.immediate)
+      case "scroll-bottom": return performScrollToBottom(effect.immediate)
+      case "scroll-key": return performScrollToKey(effect.key, { block: effect.block, smooth: effect.smooth })
     }
   }
 
-  function attachScrollIntentListeners(element: HTMLDivElement | undefined) {
-    if (detachScrollIntentListeners) {
-      detachScrollIntentListeners()
-      detachScrollIntentListeners = undefined
-    }
-    if (!element) return
-    const handleWheelIntent = (event: WheelEvent) => {
-      const dir: "up" | "down" | null = event.deltaY < 0 ? "up" : event.deltaY > 0 ? "down" : null
-      markUserScrollIntent(dir)
-    }
-    const handlePointerIntent = (event: PointerEvent) => {
-      if ((event.target as HTMLElement | null)?.closest(INTERACTIVE_KEY_TARGET_SELECTOR)) return
-      markUserScrollIntent(null)
-    }
-    const handleKeyIntent = (event: KeyboardEvent) => {
-      if (!SCROLL_INTENT_KEYS.has(event.key)) return
-      if ((event.target as HTMLElement | null)?.closest(INTERACTIVE_KEY_TARGET_SELECTOR)) return
-      const key = event.key
-      const dir: "up" | "down" | null =
-        key === "ArrowUp" || key === "PageUp" || key === "Home"
-          ? "up"
-          : key === "ArrowDown" || key === "PageDown" || key === "End"
-            ? "down"
-            : key === " " || key === "Spacebar"
-              ? event.shiftKey
-                ? "up"
-                : "down"
-              : null
-      if (key === "End") {
-        event.preventDefault()
-        scrollToBottom(true)
-        return
-      }
-      markUserScrollIntent(dir)
-    }
-    element.addEventListener("wheel", handleWheelIntent, { passive: true })
-    element.addEventListener("pointerdown", handlePointerIntent)
-    element.addEventListener("keydown", handleKeyIntent)
-    detachScrollIntentListeners = () => {
-      element.removeEventListener("wheel", handleWheelIntent)
-      element.removeEventListener("pointerdown", handlePointerIntent)
-      element.removeEventListener("keydown", handleKeyIntent)
+  function markUserScrollIntent(direction: "up" | "down" | null) {
+    cancelActiveScrollRestore()
+    scrollController.setUserIntent(direction, performance.now() + USER_SCROLL_INTENT_WINDOW_MS)
+    if (direction === "up") {
+      if (hasActiveExplicitBottomPin() || explicitBottomPinIntent()) cancelExplicitBottomPinFromUser()
+      dispatchFollowEvent({ type: "user-scroll", direction: "up", atBottom: isActuallyAtBottom() })
+    } else if (direction === "down" && isActuallyAtBottom()) {
+      dispatchFollowEvent({ type: "user-scroll", direction: "down", atBottom: true })
     }
   }
 
-  function getCurrentScrollOffset(_element: HTMLDivElement, handle: VirtualizerHandle) {
-    return handle.scrollOffset
+  function markProgrammaticScroll() {
+    programmaticScrollUntil = performance.now() + PROGRAMMATIC_SCROLL_WINDOW_MS
   }
 
-  function getCurrentScrollSize(_element: HTMLDivElement, handle: VirtualizerHandle) {
-    return handle.scrollSize
+  function hasProgrammaticScrollIntent() {
+    return performance.now() <= programmaticScrollUntil
+  }
+
+  function getCurrentMetrics(): ScrollControllerMetrics {
+    const element = scrollElement()
+    if (!element) return getManualMetrics(false)
+    return getDomMetrics(element)
   }
 
   function getDomMetrics(element: HTMLDivElement, handle = virtuaHandle(), offset = handle?.scrollOffset ?? element.scrollTop): ScrollControllerMetrics {
-    const scrollHeight = handle ? getCurrentScrollSize(element, handle) : element.scrollHeight
     return {
       offset,
-      scrollHeight,
+      scrollHeight: handle?.scrollSize ?? element.scrollHeight,
       clientHeight: handle?.viewportSize ?? element.clientHeight,
-      sentinelMarginPx: props.scrollSentinelMarginPx ?? DEFAULT_SCROLL_SENTINEL_MARGIN_PX,
+      sentinelMarginPx: BOTTOM_FOLLOW_EPSILON_PX,
     }
   }
 
+  function getManualMetrics(atBottom: boolean): ScrollControllerMetrics {
+    const clientHeight = 1000
+    return {
+      offset: 0,
+      scrollHeight: atBottom ? clientHeight : clientHeight * 2,
+      clientHeight,
+      sentinelMarginPx: BOTTOM_FOLLOW_EPSILON_PX,
+    }
+  }
+
+  function isActuallyAtBottom() {
+    const element = scrollElement()
+    if (!element) return false
+    return isAtBottom(getDomMetrics(element))
+  }
+
   function scrollToOffset(offset: number, atBottom: boolean) {
-    const handle = virtuaHandle()
     const element = scrollElement()
     if (!element) return
+    const handle = virtuaHandle()
     const maxOffset = Math.max((handle?.scrollSize ?? element.scrollHeight) - (handle?.viewportSize ?? element.clientHeight), 0)
     const nextOffset = Math.min(Math.max(offset, 0), maxOffset)
     markProgrammaticScroll()
@@ -547,297 +239,38 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
     scrollController.recordProgrammaticOffset(nextOffset, atBottom)
   }
 
-  function getManualMetrics(atBottom: boolean): ScrollControllerMetrics {
-    const clientHeight = 1000
-    const sentinelMarginPx = props.scrollSentinelMarginPx ?? DEFAULT_SCROLL_SENTINEL_MARGIN_PX
-    const distance = atBottom ? 0 : clientHeight
-    return {
-      offset: 0,
-      scrollHeight: clientHeight + distance,
-      clientHeight,
-      sentinelMarginPx,
-    }
-  }
-
-  function canRejoinFollowFromDownScroll(metrics: ScrollControllerMetrics) {
-    if (!streamingActive()) return false
-    if (effectiveSuspendAutoPinToBottom()) return false
-    if (activeHoldTargetKey() !== null) return false
-    return isAtBottom(metrics)
-  }
-
-  function getSnapshotMetrics(element: HTMLDivElement, handle?: VirtualizerHandle) {
-    const scrollTop = handle?.scrollOffset ?? element.scrollTop
-    const scrollHeight = handle ? getCurrentScrollSize(element, handle) : element.scrollHeight
-    const clientHeight = handle?.viewportSize ?? element.clientHeight
-    const maxScrollTop = Math.max(scrollHeight - clientHeight, 0)
-    const atBottom = scrollHeight - (scrollTop + clientHeight) <= (props.scrollSentinelMarginPx ?? DEFAULT_SCROLL_SENTINEL_MARGIN_PX)
-    return {
-      scrollTop,
-      scrollRatio: maxScrollTop > 0 ? scrollTop / maxScrollTop : 0,
-      maxScrollTop,
-      atBottom,
-    }
-  }
-
-  function findTopVisibleAnchor(element: HTMLDivElement) {
-    const containerRect = element.getBoundingClientRect()
-    let closestAbove: { key: string; offset: number } | null = null
-    let closestBelow: { key: string; offset: number } | null = null
-
-    for (const [key, itemElement] of itemElements) {
-      const rect = itemElement.getBoundingClientRect()
-      if (rect.bottom <= containerRect.top || rect.top >= containerRect.bottom) continue
-
-      const offset = rect.top - containerRect.top
-      if (offset <= 0) {
-        if (!closestAbove || offset > closestAbove.offset) closestAbove = { key, offset }
-      } else if (!closestBelow || offset < closestBelow.offset) {
-        closestBelow = { key, offset }
-      }
-    }
-
-    return closestAbove ?? closestBelow
-  }
-
-  function captureScrollSnapshot(): VirtualFollowScrollSnapshot | undefined {
-    const element = scrollElement()
-    if (!element) return undefined
-
-    const snapshot: VirtualFollowScrollSnapshot = getSnapshotMetrics(element, virtuaHandle())
-    const currentMode = hasActiveBottomFollowIntent() ? ({ type: "following" } as const) : followMode()
-    Object.assign(snapshot, getFollowSnapshotState(currentMode, suspendHeldAnchorUntilBottom))
-    if (hasActiveBottomFollowIntent()) {
-      snapshot.atBottom = true
-      delete snapshot.anchorKey
-      delete snapshot.anchorOffset
-      return snapshot
-    }
-    if (!snapshot.atBottom) {
-      const anchor = findTopVisibleAnchor(element)
-      if (anchor) {
-        snapshot.anchorKey = anchor.key
-        snapshot.anchorOffset = anchor.offset
-      }
-    }
-    return snapshot
-  }
-
-  function applyPixelSnapshot(snapshot: VirtualFollowScrollSnapshot, behavior: ScrollBehavior) {
-    const element = scrollElement()
-    if (!element) return
-
-    const handle = virtuaHandle()
-    const maxScrollTop = Math.max((handle?.scrollSize ?? element.scrollHeight) - (handle?.viewportSize ?? element.clientHeight), 0)
-    const scrollRatio = snapshot.scrollRatio
-    const canUseRatio =
-      !snapshot.atBottom &&
-      typeof scrollRatio === "number" &&
-      Number.isFinite(scrollRatio) &&
-      snapshot.maxScrollTop !== maxScrollTop
-    const nextTop = snapshot.atBottom
-      ? maxScrollTop
-      : canUseRatio
-        ? Math.min(Math.max(scrollRatio, 0), 1) * maxScrollTop
-        : Math.min(snapshot.scrollTop, maxScrollTop)
-
-    if (behavior === "smooth" && !virtuaHandle()) {
-      markProgrammaticScroll()
-      element.scrollTo({ top: nextTop, behavior })
-      scrollController.recordProgrammaticOffset(nextTop, snapshot.atBottom)
-      return
-    }
-    scrollToOffset(nextTop, snapshot.atBottom)
-  }
-
-  function applyAnchorSnapshot(snapshot: VirtualFollowScrollSnapshot) {
-    const element = scrollElement()
-    if (!element || !snapshot.anchorKey || typeof snapshot.anchorOffset !== "number") return false
-
-    const itemWrapper = itemElements.get(snapshot.anchorKey)
-    if (!itemWrapper) return false
-
-    const containerRect = element.getBoundingClientRect()
-    const itemRect = itemWrapper.getBoundingClientRect()
-    const currentOffset = itemRect.top - containerRect.top
-    const delta = currentOffset - snapshot.anchorOffset
-    if (Math.abs(delta) > 1) {
-      scrollToOffset((virtuaHandle()?.scrollOffset ?? element.scrollTop) + delta, false)
-    }
-    return true
-  }
-
-  function applyBottomSnapshot() {
-    const element = scrollElement()
-    if (!element) return
-    const handle = virtuaHandle()
-    const maxOffset = Math.max((handle?.scrollSize ?? element.scrollHeight) - (handle?.viewportSize ?? element.clientHeight), 0)
-    scrollToOffset(maxOffset, true)
-  }
-
-  function restoreScrollSnapshot(snapshot: VirtualFollowScrollSnapshot, opts?: RestoreScrollSnapshotOptions) {
-    const element = scrollElement()
-    if (!element) {
-      opts?.fallback?.()
-      return
-    }
-
-    if (hasActiveBottomFollowIntent()) {
-      scheduleBottomFollowIntentFrame()
-      opts?.onApplied?.()
-      return
-    }
-
-    const token = ++restoreToken
-    const isRestoreCurrent = () => token === restoreToken && Boolean(scrollElement())
-    const behavior = opts?.behavior ?? "auto"
-    scrollController.setRestoring(true)
-    const finishRestore = () => {
-      if (!isRestoreCurrent()) return
-      applyRestoredFollowSnapshot(snapshot)
-      scrollController.setRestoring(false)
-      opts?.onApplied?.()
-    }
-    if (snapshot.atBottom) {
-      applyBottomSnapshot()
-      requestAnimationFrame(() => {
-        if (!isRestoreCurrent()) return
-        applyBottomSnapshot()
-        finishRestore()
-      })
-      return
-    }
-
-    if (snapshot.anchorKey) {
-      const index = props.items().findIndex((item, i) => props.getKey(item, i) === snapshot.anchorKey)
-      if (index !== -1) {
-        markProgrammaticScroll()
-        virtuaHandle()?.scrollToIndex(index, { align: "start", smooth: behavior === "smooth" })
-        retryAnchorRestore(snapshot, behavior, 6, isRestoreCurrent, finishRestore)
-        return
-      }
-    }
-
-    applyPixelSnapshot(snapshot, behavior)
-    requestAnimationFrame(finishRestore)
-  }
-
-  function retryAnchorRestore(
-    snapshot: VirtualFollowScrollSnapshot,
-    behavior: ScrollBehavior,
-    remainingFrames: number,
-    isCurrent: () => boolean,
-    onApplied?: () => void,
-  ) {
-    requestAnimationFrame(() => {
-      if (!isCurrent()) return
-      const applied = applyAnchorSnapshot(snapshot)
-      if (applied) {
-        requestAnimationFrame(() => {
-          if (!isCurrent()) return
-          applyAnchorSnapshot(snapshot)
-          onApplied?.()
-        })
-        return
-      }
-
-      if (remainingFrames > 0) {
-        retryAnchorRestore(snapshot, behavior, remainingFrames - 1, isCurrent, onApplied)
-        return
-      }
-
-      applyPixelSnapshot(snapshot, behavior)
-      requestAnimationFrame(() => {
-        if (!isCurrent()) return
-        onApplied?.()
-      })
-    })
-  }
-
-  function updateScrollButtons() {
-    const handle = virtuaHandle()
-    const element = scrollElement()
-    if (!handle || !element) return
-
-    const previousSnapshot = scrollController.snapshot()
-    const offset = getCurrentScrollOffset(element, handle)
-    const now = performance.now()
-    const programmatic = hasProgrammaticScrollIntent()
-    const hasFreshUserIntent = now <= previousSnapshot.userIntentUntil
-    const metrics = getDomMetrics(element, handle, offset)
-    const atBottom = isAtBottom(metrics)
-    const atTop = offset <= (props.scrollSentinelMarginPx ?? DEFAULT_SCROLL_SENTINEL_MARGIN_PX)
-
-    const hasItems = props.items().length > 0
-    setShowScrollBottomButton(hasItems && !atBottom)
-    setShowScrollTopButton(hasItems && !atTop)
-
-    const result = scrollController.observeViewport(
-      metrics,
-      now,
-      programmatic,
-      canRejoinFollowFromDownScroll(metrics),
-      autoPinHoldEnabled() && streamingActive(),
-    )
-    const manualHoldScroll =
-      previousSnapshot.mode.type === "holding" &&
-      result.state.mode.type === "holding" &&
-      hasFreshUserIntent &&
-      Math.abs(offset - previousSnapshot.lastObservedOffset) > 1
-    if (manualHoldScroll) {
-      suspendHeldAnchorUntilBottom = true
-      clearHeldAnchor()
-    }
-    if (result.state.mode.type !== followMode().type || result.effect.type !== "none") {
-      suppressHoldUntilTargetChanges = false
-    }
-    syncControllerResult(result)
-    if (result.state.mode.type === "holding" && shouldManageHeldAnchor(result.state.mode.key)) {
-      captureHeldAnchor(result.state.mode.key)
-    }
-  }
-
   function performScrollToBottom(immediate = true) {
     const handle = virtuaHandle()
     const element = scrollElement()
-    if (!handle || props.items().length === 0) return
-    if (immediate && element) {
-      markProgrammaticScroll()
-      handle.scrollToIndex(props.items().length - 1, { align: "end", smooth: false })
-      pinDomBottomAfterLayout()
-      return
-    }
+    if (props.items().length === 0) return
     markProgrammaticScroll()
-    handle.scrollToIndex(props.items().length - 1, { align: "end", smooth: !immediate })
+    if (handle) {
+      handle.scrollToIndex(props.items().length - 1, { align: "end", smooth: !immediate })
+    } else if (element) {
+      scrollToOffset(element.scrollHeight - element.clientHeight, true)
+    }
+    pinDomBottomAfterLayout()
   }
 
   function pinDomBottomAfterLayout(remainingFrames = 2) {
     const element = scrollElement()
-    if (!element) return
-    if (!autoScroll() || effectiveSuspendAutoPinToBottom() || scrollController.snapshot().restoring) return
-    if (shouldHonorPrePinEscape() && escapeFollowIfDomMovedUp(element)) return
-
+    if (!element || !autoScroll() || externalSuspendAutoPinToBottom() || scrollController.snapshot().restoring) return
     const handle = virtuaHandle()
     const maxOffset = Math.max((handle?.scrollSize ?? element.scrollHeight) - (handle?.viewportSize ?? element.clientHeight), 0)
     scrollToOffset(maxOffset, true)
     if (remainingFrames <= 0) return
-
-    requestAnimationFrame(() => {
-      if (!autoScroll() || effectiveSuspendAutoPinToBottom() || scrollController.snapshot().restoring) return
-      pinDomBottomAfterLayout(remainingFrames - 1)
-    })
+    requestAnimationFrame(() => pinDomBottomAfterLayout(remainingFrames - 1))
   }
 
   function performScrollToTop(immediate = true) {
     const handle = virtuaHandle()
-    const element = scrollElement()
-    if (!handle) return
-    if (immediate && element) {
+    if (immediate) {
       scrollToOffset(0, false)
       return
     }
+    if (!handle) return
     markProgrammaticScroll()
-    handle.scrollToIndex(0, { align: "start", smooth: !immediate })
+    handle.scrollToIndex(0, { align: "start", smooth: true })
   }
 
   function performScrollToKey(key: string, opts: { block: ScrollLogicalPosition; smooth: boolean }) {
@@ -847,37 +280,49 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
     virtuaHandle()?.scrollToIndex(index, { align: opts.block, smooth: opts.smooth })
   }
 
-  function scrollToBottom(immediate = true, options?: { suppressAutoAnchor?: boolean; suppressHold?: boolean }) {
-    if (options?.suppressAutoAnchor ?? !immediate) {
-      suppressAutoScrollOnce = true
-    }
-    dispatchFollowEvent({ type: "jump-bottom", immediate, explicit: options?.suppressHold ?? false })
-  }
+  function updateScrollStateFromDom() {
+    const handle = virtuaHandle()
+    const element = scrollElement()
+    if (!handle || !element) return
 
-  function scrollToTop(immediate = true) {
-    dispatchFollowEvent({ type: "jump-top", immediate })
+    const offset = handle.scrollOffset
+    const metrics = getDomMetrics(element, handle, offset)
+    const atBottom = isAtBottom(metrics)
+    const atTop = offset <= TOP_SCROLL_EPSILON_PX
+    const hasItems = props.items().length > 0
+    setShowScrollBottomButton(hasItems && !atBottom)
+    setShowScrollTopButton(hasItems && !atTop)
+
+    const now = performance.now()
+    const programmatic = hasProgrammaticScrollIntent()
+    const result = scrollController.observeViewport(metrics, now, programmatic)
+    if (result.state.mode.type === "escaped" && explicitBottomPinIntent()) {
+      cancelExplicitBottomPinFromUser()
+    }
+    syncControllerResult(result)
   }
 
   function handleScroll() {
-    updateScrollButtons()
+    updateScrollStateFromDom()
     props.onScroll?.()
 
-    // Find active key (roughly the first visible item)
     const handle = virtuaHandle()
     const element = scrollElement()
-    if (handle && element) {
-      const start = handle.findItemIndex(getCurrentScrollOffset(element, handle))
-      const items = props.items()
-      if (items[start]) {
-        const key = props.getKey(items[start], start)
-        if (key !== activeKey()) {
-          setActiveKey(key)
-          props.onActiveKeyChange?.(key)
-        }
-      }
+    if (!handle || !element) return
+    const start = handle.findItemIndex(handle.scrollOffset)
+    const item = props.items()[start]
+    if (!item) return
+    const key = props.getKey(item, start)
+    if (key !== activeKey()) {
+      setActiveKey(key)
+      props.onActiveKeyChange?.(key)
     }
   }
 
+  function getAnchorIdForKey(key: string) {
+    return props.getAnchorId ? props.getAnchorId(key) : key
+  }
+
   function registerItemElement(key: string, element: HTMLDivElement | null | undefined) {
     if (!element) {
       itemElements.delete(key)
@@ -886,174 +331,347 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
     itemElements.set(key, element)
   }
 
-  function getAnchorIdForKey(key: string) {
-    return props.getAnchorId ? props.getAnchorId(key) : key
-  }
-
-  function resolveHoldTargetElement(key: string) {
-    const itemWrapper = itemElements.get(key)
-    return resolveAutoPinHoldElement(itemWrapper, key, props.resolveAutoPinHoldElement)
-  }
-
-  function clearHeldAnchor() {
-    heldAnchorKey = null
-    heldAnchorElement = null
-    heldAnchorOffset = null
-  }
-
-  function captureHeldAnchor(key = activeHoldTargetKey(), target?: HTMLElement | null) {
+  function maybeEscapeForHoldTrigger() {
+    if (!streamingActive() || !autoPinHoldEnabled() || !autoScroll() || externalSuspendAutoPinToBottom()) return false
     const element = scrollElement()
-    if (!element || !key || !shouldManageHeldAnchor(key)) return false
-    const resolvedTarget = target ?? (
-      heldAnchorKey === key && heldAnchorElement && element.contains(heldAnchorElement)
-        ? heldAnchorElement
-        : resolveHoldTargetElement(key)
-    )
-    if (!resolvedTarget || !element.contains(resolvedTarget)) return false
+    const key = holdTargetKey()
+    if (!element || !key) return false
+    const target = resolveAutoPinHoldElement(itemElements.get(key), key, props.resolveAutoPinHoldElement)
+    if (!target) return false
+
     const containerRect = element.getBoundingClientRect()
-    const targetRect = resolvedTarget.getBoundingClientRect()
-    heldAnchorKey = key
-    heldAnchorElement = resolvedTarget
-    heldAnchorOffset = targetRect.top - containerRect.top
+    const targetRect = target.getBoundingClientRect()
+    if (targetRect.height <= element.clientHeight) return false
+    if (targetRect.top - containerRect.top - holdTargetTopThresholdPx() > 1) return false
+
+    dispatchFollowEvent({ type: "set-follow", enabled: false })
+    scrollController.recordProgrammaticOffset(virtuaHandle()?.scrollOffset ?? element.scrollTop, isActuallyAtBottom())
     return true
   }
 
-  function restoreHeldAnchor() {
-    const key = activeHoldTargetKey()
-    const element = scrollElement()
-    if (!element || !key || heldAnchorKey !== key || heldAnchorOffset === null) return false
-    const target = heldAnchorElement
-    if (!target || !element.contains(target)) {
-      clearHeldAnchor()
-      return false
-    }
-
-    const containerRect = element.getBoundingClientRect()
-    const targetRect = target.getBoundingClientRect()
-    const currentOffset = targetRect.top - containerRect.top
-    const delta = currentOffset - heldAnchorOffset
-    if (Math.abs(delta) > 1) {
-      scrollToOffset((virtuaHandle()?.scrollOffset ?? element.scrollTop) + delta, false)
-    }
-    captureHeldAnchor(key, target)
-    return true
-  }
-
-  function alignHoldTarget(key: string) {
-    if (activeHoldTargetKey() !== key) return
-    if (!shouldManageHeldAnchor(key)) return
-    const element = scrollElement()
-    if (!element) return
-    const target = resolveHoldTargetElement(key)
-    if (!target) return
-    const containerRect = element.getBoundingClientRect()
-    const targetRect = target.getBoundingClientRect()
-    const relativeTop = targetRect.top - containerRect.top
-    const alignDelta = relativeTop - holdTargetTopThresholdPx()
-    if (Math.abs(alignDelta) > 1) {
-      scrollToOffset((virtuaHandle()?.scrollOffset ?? element.scrollTop) + alignDelta, false)
-    }
-    captureHeldAnchor(key, target)
-    requestAnimationFrame(() => captureHeldAnchor(key, target))
-  }
-
-  function updateAutoPinHold() {
-    const element = scrollElement()
-    if (!element) return
-    if (hasActiveBottomFollowIntent()) return
-
-    const targetKey = holdTargetKey()
-    const heldKey = activeHoldTargetKey()
-
-    if (heldKey !== null) {
-      if (targetKey !== heldKey) {
-        suspendHeldAnchorUntilBottom = true
-        clearHeldAnchor()
-        dispatchFollowEvent({ type: "hold-target-changed", key: targetKey, canPinToBottom: !externalSuspendAutoPinToBottom() })
-      }
-      if (shouldManageHeldAnchor(heldKey, targetKey) && (heldAnchorKey !== heldKey || heldAnchorOffset === null)) {
-        captureHeldAnchor(heldKey)
-      }
-
-      return
-    }
-
-    if (!streamingActive()) return
-    if (!autoPinHoldEnabled()) return
-    if (!autoScroll()) return
-    if (externalSuspendAutoPinToBottom()) return
-    if (!targetKey) return
-    if (didTriggerHoldForCurrentTarget()) return
-    if (suppressHoldUntilTargetChanges) return
-
-    const itemWrapper = itemElements.get(targetKey)
-    const target = resolveAutoPinHoldElement(itemWrapper, targetKey, props.resolveAutoPinHoldElement)
-    if (!target) return
-
-    const containerRect = element.getBoundingClientRect()
-    const targetRect = target.getBoundingClientRect()
-    const relativeTop = targetRect.top - containerRect.top
-    const exceedsViewport = targetRect.height > element.clientHeight
-
-    if (exceedsViewport && relativeTop <= holdTargetTopThresholdPx()) {
-      dispatchFollowEvent({ type: "hold-candidate", key: targetKey, shouldHold: true })
-      setDidTriggerHoldForCurrentTarget(true)
-    }
-  }
-
   function flushContentRendered() {
     pendingContentRenderedFrame = null
-
-    if (hasActiveBottomFollowIntent()) {
-      scheduleBottomFollowIntentFrame()
-      updateScrollButtons()
+    if (restartAnchorRestore) {
+      restartAnchorRestore()
+      updateScrollStateFromDom()
+      return
+    }
+    if (hasActiveExplicitBottomPin()) {
+      scheduleExplicitBottomPinFrame()
+      updateScrollStateFromDom()
       return
     }
 
-    if (shouldHonorPrePinEscape() && escapeFollowIfDomMovedUp()) {
-      updateScrollButtons()
+    if (maybeEscapeForHoldTrigger()) {
+      updateScrollStateFromDom()
       return
     }
 
-    updateAutoPinHold()
-    if (activeHoldTargetKey() !== null) {
-      if (autoScroll() && streamingActive()) pendingBottomRepinAfterHold = true
-      if (shouldManageHeldAnchor()) {
-        restoreHeldAnchor()
+    dispatchFollowEvent({ type: "content-grew", canPinToBottom: autoScroll() && !externalSuspendAutoPinToBottom() })
+    updateScrollStateFromDom()
+  }
+
+  function hasActiveExplicitBottomPin() {
+    return explicitBottomPinToken !== null
+  }
+
+  function clearExplicitBottomPin() {
+    explicitBottomPinToken = null
+    explicitBottomPinMinItemCount = 0
+    explicitBottomPinSettleFrames = 0
+    explicitBottomPinFramesRemaining = 0
+  }
+
+  function cancelExplicitBottomPinFromUser() {
+    userCancelledExplicitBottomPinToken = explicitBottomPinToken ?? explicitBottomPinIntent()?.token ?? null
+    clearExplicitBottomPin()
+    props.onExplicitBottomPinCancelled?.()
+  }
+
+  function startExplicitBottomPin(intent: VirtualExplicitBottomPinIntent) {
+    cancelActiveScrollRestore()
+    userCancelledExplicitBottomPinToken = null
+    explicitBottomPinToken = intent.token
+    explicitBottomPinMinItemCount = Math.max(0, Math.floor(intent.minItemCount ?? 0))
+    explicitBottomPinSettleFrames = EXPLICIT_BOTTOM_PIN_SETTLE_FRAMES
+    explicitBottomPinFramesRemaining = EXPLICIT_BOTTOM_PIN_MAX_FRAMES
+    runExplicitBottomPinFrame()
+  }
+
+  function scheduleExplicitBottomPinFrame() {
+    if (!hasActiveExplicitBottomPin() || pendingExplicitBottomPinFrame !== null) return
+    pendingExplicitBottomPinFrame = requestAnimationFrame(() => runExplicitBottomPinFrame())
+  }
+
+  function runExplicitBottomPinFrame() {
+    pendingExplicitBottomPinFrame = null
+    if (!hasActiveExplicitBottomPin()) return
+    dispatchFollowEvent({ type: "jump-bottom", immediate: true, explicit: true })
+
+    const ready = props.items().length >= explicitBottomPinMinItemCount && isActuallyAtBottom()
+    if (ready) explicitBottomPinSettleFrames -= 1
+    else explicitBottomPinSettleFrames = EXPLICIT_BOTTOM_PIN_SETTLE_FRAMES
+    explicitBottomPinFramesRemaining -= 1
+
+    if ((ready && explicitBottomPinSettleFrames <= 0) || explicitBottomPinFramesRemaining <= 0) {
+      clearExplicitBottomPin()
+      return
+    }
+    scheduleExplicitBottomPinFrame()
+  }
+
+  function captureScrollSnapshot(): VirtualFollowScrollSnapshot | undefined {
+    const element = scrollElement()
+    if (!element) return undefined
+    const handle = virtuaHandle()
+    const scrollTop = handle?.scrollOffset ?? element.scrollTop
+    const scrollHeight = handle?.scrollSize ?? element.scrollHeight
+    const clientHeight = handle?.viewportSize ?? element.clientHeight
+    const maxScrollTop = Math.max(scrollHeight - clientHeight, 0)
+    const atBottom = isAtBottom(getDomMetrics(element, handle, scrollTop))
+    const snapshot: VirtualFollowScrollSnapshot = {
+      scrollTop,
+      scrollRatio: maxScrollTop > 0 ? scrollTop / maxScrollTop : 0,
+      maxScrollTop,
+      atBottom,
+      ...getFollowSnapshotState(followMode()),
+    }
+    if (!atBottom) {
+      const anchor = findTopVisibleAnchor(element)
+      if (anchor) {
+        snapshot.anchorKey = anchor.key
+        snapshot.anchorOffset = anchor.offset
       }
-      updateScrollButtons()
+    }
+    return snapshot
+  }
+
+  function findTopVisibleAnchor(element: HTMLDivElement) {
+    const containerRect = element.getBoundingClientRect()
+    const candidates = []
+    for (const [key, itemElement] of itemElements) {
+      if (!itemElement.isConnected) continue
+      const rect = itemElement.getBoundingClientRect()
+      candidates.push({ key, top: rect.top, bottom: rect.bottom })
+    }
+    const handle = virtuaHandle()
+    const index = handle?.findItemIndex(handle.scrollOffset)
+    const item = typeof index === "number" ? props.items()[index] : undefined
+    const preferredKey = item === undefined || index === undefined ? undefined : props.getKey(item, index)
+    const anchor = selectTopViewportAnchor(candidates, containerRect.top, containerRect.bottom, preferredKey)
+    return anchor ? { key: anchor.key, offset: anchor.top - containerRect.top } : null
+  }
+
+  function restoreScrollSnapshot(snapshot: VirtualFollowScrollSnapshot, opts?: RestoreScrollSnapshotOptions) {
+    const element = scrollElement()
+    if (!element) {
+      opts?.fallback?.()
+      return
+    }
+    if (hasActiveExplicitBottomPin()) {
+      scheduleExplicitBottomPinFrame()
+      opts?.onApplied?.()
       return
     }
 
-    const canPinToBottom = autoScroll() && !effectiveSuspendAutoPinToBottom()
-    dispatchFollowEvent({ type: "content-grew", canPinToBottom })
-    updateScrollButtons()
+    const token = restoreToken.begin()
+    const isCurrent = () => restoreToken.isCurrent(token) && Boolean(scrollElement())
+    restartAnchorRestore = undefined
+    scrollController.setRestoring(true)
+    cancelRestore = () => opts?.onCancelled?.()
+
+    const finish = () => {
+      if (!isCurrent()) return
+      restartAnchorRestore = undefined
+      cancelRestore = undefined
+      const mode = restoreFollowModeFromSnapshot(snapshot)
+      setFollowMode(mode)
+      scrollController.restoreMode(mode)
+      scrollController.setRestoring(false)
+      opts?.onApplied?.()
+    }
+
+    if (snapshot.atBottom) {
+      performScrollToBottom(true)
+      requestAnimationFrame(finish)
+      return
+    }
+
+    if (snapshot.anchorKey) {
+      const index = props.items().findIndex((item, i) => props.getKey(item, i) === snapshot.anchorKey)
+      if (index !== -1) {
+        markProgrammaticScroll()
+        virtuaHandle()?.scrollToIndex(index, { align: "start", smooth: opts?.behavior === "smooth" })
+        const stabilizer = new AnchorRestoreStabilizer()
+        restartAnchorRestore = () => {
+          if (!isCurrent()) return
+          stabilizer.restartStability()
+          scrollToAnchorIndex(snapshot.anchorKey!)
+        }
+        retryAnchorRestore(snapshot, stabilizer, isCurrent, finish)
+        return
+      }
+    }
+
+    applyPixelSnapshot(snapshot, opts?.behavior ?? "auto")
+    requestAnimationFrame(finish)
+  }
+
+  function scrollToAnchorIndex(key: string) {
+    const index = props.items().findIndex((item, i) => props.getKey(item, i) === key)
+    if (index === -1) return false
+    markProgrammaticScroll()
+    virtuaHandle()?.scrollToIndex(index, { align: "start", smooth: false })
+    return true
+  }
+
+  function retryAnchorRestore(snapshot: VirtualFollowScrollSnapshot, stabilizer: AnchorRestoreStabilizer, isCurrent: () => boolean, onApplied: () => void) {
+    requestAnimationFrame(() => {
+      if (!isCurrent()) return
+      const element = scrollElement()
+      const key = snapshot.anchorKey!
+      const targetExists = props.items().some((item, index) => props.getKey(item, index) === key)
+      const itemWrapper = itemElements.get(key)
+      const anchorOffset = snapshot.anchorOffset
+      const mounted = Boolean(element && itemWrapper?.isConnected)
+      const delta = mounted && element && itemWrapper && typeof anchorOffset === "number"
+        ? itemWrapper.getBoundingClientRect().top - element.getBoundingClientRect().top - anchorOffset
+        : undefined
+      const result = stabilizer.nextFrame({ targetExists, mounted, delta })
+
+      if (result.type === "finish") {
+        onApplied()
+        return
+      }
+      if (result.type === "correct" && element) {
+        scrollToOffset((virtuaHandle()?.scrollOffset ?? element.scrollTop) + result.delta, false)
+        if (result.finishAfterCorrection) {
+          restartAnchorRestore = () => {}
+          requestAnimationFrame(onApplied)
+          return
+        }
+      }
+      if (result.type === "retry" && result.reissueIndex) scrollToAnchorIndex(key)
+      if (result.type !== "fallback") {
+        retryAnchorRestore(snapshot, stabilizer, isCurrent, onApplied)
+        return
+      }
+      applyPixelSnapshot(snapshot, "auto")
+      onApplied()
+    })
+  }
+
+  function applyPixelSnapshot(snapshot: VirtualFollowScrollSnapshot, behavior: ScrollBehavior) {
+    const element = scrollElement()
+    if (!element) return
+    const handle = virtuaHandle()
+    const maxScrollTop = Math.max((handle?.scrollSize ?? element.scrollHeight) - (handle?.viewportSize ?? element.clientHeight), 0)
+    const nextTop = snapshot.atBottom
+      ? maxScrollTop
+      : typeof snapshot.scrollRatio === "number" && snapshot.maxScrollTop !== maxScrollTop
+        ? Math.min(Math.max(snapshot.scrollRatio, 0), 1) * maxScrollTop
+        : Math.min(snapshot.scrollTop, maxScrollTop)
+    if (behavior === "smooth" && !handle) {
+      markProgrammaticScroll()
+      element.scrollTo({ top: nextTop, behavior })
+      scrollController.recordProgrammaticOffset(nextTop, snapshot.atBottom)
+      return
+    }
+    scrollToOffset(nextTop, snapshot.atBottom)
+  }
+
+  function attachScrollIntentListeners(element: HTMLDivElement | undefined) {
+    detachScrollIntentListeners?.()
+    detachScrollIntentListeners = undefined
+    if (!element) return
+    const handleWheelIntent = (event: WheelEvent) => markUserScrollIntent(event.deltaY < 0 ? "up" : event.deltaY > 0 ? "down" : null)
+    const handlePointerIntent = (event: PointerEvent) => {
+      if ((event.target as HTMLElement | null)?.closest(INTERACTIVE_KEY_TARGET_SELECTOR)) return
+      markUserScrollIntent(null)
+    }
+    let lastTouchY: number | null = null
+    const handleTouchStart = (event: TouchEvent) => {
+      lastTouchY = event.touches[0]?.clientY ?? null
+      markUserScrollIntent(null)
+    }
+    const handleTouchMove = (event: TouchEvent) => {
+      const nextY = event.touches[0]?.clientY ?? null
+      const previousY = lastTouchY
+      lastTouchY = nextY
+      if (nextY === null || previousY === null) {
+        markUserScrollIntent(null)
+        return
+      }
+      markUserScrollIntent(nextY > previousY ? "up" : nextY < previousY ? "down" : null)
+    }
+    const handleTouchEnd = () => {
+      lastTouchY = null
+    }
+    const handleKeyIntent = (event: KeyboardEvent) => {
+      if (!isActive()) return
+      if (!SCROLL_INTENT_KEYS.has(event.key)) return
+      if ((event.target as HTMLElement | null)?.closest(INTERACTIVE_KEY_TARGET_SELECTOR)) return
+      if (event.key === "End") {
+        event.preventDefault()
+        scrollToBottom(true)
+        return
+      }
+      if (event.key === "Home") {
+        event.preventDefault()
+        scrollToTop(true)
+        return
+      }
+      const direction = event.key === "ArrowUp" || event.key === "PageUp" || event.key === "Home" || (event.shiftKey && (event.key === " " || event.key === "Spacebar"))
+        ? "up"
+        : "down"
+      markUserScrollIntent(direction)
+    }
+    element.addEventListener("wheel", handleWheelIntent, { passive: true })
+    element.addEventListener("pointerdown", handlePointerIntent)
+    element.addEventListener("touchstart", handleTouchStart, { passive: true })
+    element.addEventListener("touchmove", handleTouchMove, { passive: true })
+    element.addEventListener("touchend", handleTouchEnd, { passive: true })
+    element.addEventListener("touchcancel", handleTouchEnd, { passive: true })
+    element.addEventListener("keydown", handleKeyIntent)
+    detachScrollIntentListeners = () => {
+      element.removeEventListener("wheel", handleWheelIntent)
+      element.removeEventListener("pointerdown", handlePointerIntent)
+      element.removeEventListener("touchstart", handleTouchStart)
+      element.removeEventListener("touchmove", handleTouchMove)
+      element.removeEventListener("touchend", handleTouchEnd)
+      element.removeEventListener("touchcancel", handleTouchEnd)
+      element.removeEventListener("keydown", handleKeyIntent)
+    }
+  }
+
+  function scrollToBottom(immediate = true) {
+    cancelActiveScrollRestore()
+    dispatchFollowEvent({ type: "jump-bottom", immediate, explicit: true })
+  }
+
+  function scrollToTop(immediate = true) {
+    cancelActiveScrollRestore()
+    dispatchFollowEvent({ type: "jump-top", immediate })
+  }
+
+  function scrollToKey(key: string, opts?: { behavior?: ScrollBehavior; block?: ScrollLogicalPosition }) {
+    cancelActiveScrollRestore()
+    dispatchFollowEvent({ type: "jump-key", key, block: opts?.block ?? "start", smooth: opts?.behavior === "smooth" })
   }
 
   const api: VirtualFollowListApi = {
     scrollToTop: (opts) => scrollToTop(opts?.immediate ?? true),
-    scrollToBottom: (opts) => scrollToBottom(opts?.immediate ?? true, { suppressAutoAnchor: opts?.suppressAutoAnchor, suppressHold: opts?.suppressHold }),
-    scrollToKey: (key, opts) => {
-      const index = props.items().findIndex((item, i) => props.getKey(item, i) === key)
-      if (index === -1) return
-      const nextAutoScroll = opts?.setAutoScroll ?? false
-      dispatchFollowEvent({
-        type: "jump-key",
-        key,
-        block: opts?.block ?? "start",
-        smooth: opts?.behavior === "smooth",
-        followAfter: nextAutoScroll,
-      })
-    },
+    scrollToBottom: (opts) => scrollToBottom(opts?.immediate ?? true),
+    scrollToKey,
     notifyContentRendered: () => {
-      if (typeof requestAnimationFrame !== "function") {
-        flushContentRendered()
+      if (restartAnchorRestore) {
+        restartAnchorRestore()
         return
       }
       if (pendingContentRenderedFrame !== null) return
       pendingContentRenderedFrame = requestAnimationFrame(() => flushContentRendered())
     },
-    setAutoScroll: (enabled) => dispatchFollowEvent({ type: "set-follow", enabled: Boolean(enabled) }),
+    setAutoScroll: (enabled) => dispatchFollowEvent({ type: "set-follow", enabled }),
     getAutoScroll: () => autoScroll(),
     getScrollElement: () => scrollElement(),
     getShellElement: () => shellElement(),
@@ -1064,120 +682,55 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
   createEffect(() => props.registerApi?.(api))
   createEffect(() => props.registerState?.(state))
 
-  createEffect(on(() => props.resetKey?.(), () => {
-    itemElements.clear()
-    setDidTriggerHoldForCurrentTarget(false)
-    suppressHoldUntilTargetChanges = false
-    suspendHeldAnchorUntilBottom = false
-    pendingBottomRepinAfterHold = false
-    clearHeldAnchor()
-  }))
-
-  createEffect(on(holdTargetKey, (nextTargetKey, prevTargetKey) => {
-    if (nextTargetKey !== prevTargetKey && didTriggerHoldForCurrentTarget()) {
-      setDidTriggerHoldForCurrentTarget(false)
-    }
-    if (nextTargetKey !== prevTargetKey && !hasActiveBottomFollowIntent()) {
-      suppressHoldUntilTargetChanges = false
-    }
-    if (activeHoldTargetKey() === null) return
-    if (nextTargetKey === activeHoldTargetKey()) return
-    suspendHeldAnchorUntilBottom = true
-    clearHeldAnchor()
-    dispatchFollowEvent({ type: "hold-target-changed", key: nextTargetKey, canPinToBottom: !externalSuspendAutoPinToBottom() })
-    if (pendingBottomRepinAfterHold) {
-      pendingBottomRepinAfterHold = false
-      requestAnimationFrame(() => pinDomBottomAfterLayout())
-    }
-  }, { defer: true }))
-
-  createEffect(on(autoPinHoldEnabled, (enabled) => {
-    if (enabled) return
-    setDidTriggerHoldForCurrentTarget(false)
-    suppressHoldUntilTargetChanges = false
-    suspendHeldAnchorUntilBottom = false
-    pendingBottomRepinAfterHold = false
-    if (activeHoldTargetKey() !== null) {
-      dispatchFollowEvent({
-        type: "clear-hold",
-        follow: true,
-        canPinToBottom: !externalSuspendAutoPinToBottom(),
-        suppressHold: true,
-      })
+  createEffect(on(explicitBottomPinIntent, (intent) => {
+    if (!intent) {
+      userCancelledExplicitBottomPinToken = null
+      clearExplicitBottomPin()
       return
     }
-    clearHeldAnchor()
-  }, { defer: true }))
+    if (intent.token === userCancelledExplicitBottomPinToken) return
+    if (intent.token === explicitBottomPinToken) return
+    startExplicitBottomPin(intent)
+  }))
 
-  createEffect(on(forceBottomFollowIntent, (intent) => {
-    if (!intent) return
-    if (intent.token === bottomFollowIntentToken) return
-    startBottomFollowIntent(intent)
-  }, { defer: true }))
-
-  // Handle autoScroll (Follow) on items change
   createEffect(on(() => props.items().length, (len, prevLen) => {
     if (pendingInitialScroll && isActive() && len > 0) {
       pendingInitialScroll = false
-      if (initialScrollToBottom()) {
-        dispatchFollowEvent({ type: "jump-bottom", immediate: true, explicit: false })
-      }
-      suppressAutoScrollOnce = false
+      if (initialScrollToBottom()) scrollToBottom(true)
       return
     }
-    if (len > (prevLen ?? 0) && autoScroll() && !effectiveSuspendAutoPinToBottom() && !suppressAutoScrollOnce) {
-      if (hasActiveBottomFollowIntent()) {
-        scheduleBottomFollowIntentFrame()
-        suppressAutoScrollOnce = false
-        return
-      }
-      requestAnimationFrame(() => {
-        dispatchFollowEvent({ type: "content-grew", canPinToBottom: autoScroll() && !effectiveSuspendAutoPinToBottom() })
-      })
-    }
-    suppressAutoScrollOnce = false
+    if (len > (prevLen ?? 0) && autoScroll()) api.notifyContentRendered()
   }, { defer: true }))
 
-  // Handle followToken change
   createEffect(on(() => props.followToken?.(), () => {
-    const canPinToBottom = autoScroll() && !effectiveSuspendAutoPinToBottom()
-    if (canPinToBottom) {
-      dispatchFollowEvent({ type: "content-grew", canPinToBottom })
-    }
+    if (autoScroll()) api.notifyContentRendered()
   }, { defer: true }))
 
-  // Reset state on resetKey change
   createEffect(on(() => props.resetKey?.(), (nextKey) => {
     if (nextKey === lastResetKey) return
     lastResetKey = nextKey
-    dispatchFollowEvent({ type: "reset", follow: Boolean(initialAutoScroll()) })
+    invalidateScrollRestore()
+    clearExplicitBottomPin()
+    dispatchFollowEvent({ type: "reset", follow: initialAutoScroll() })
     pendingInitialScroll = true
+    itemElements.clear()
   }))
 
-  // Initial scroll and session activation
   createEffect(on(isActive, (active) => {
     if (!active) return
     if (pendingInitialScroll && props.items().length > 0) {
       pendingInitialScroll = false
-      if (initialScrollToBottom()) {
-        dispatchFollowEvent({ type: "jump-bottom", immediate: true, explicit: false })
-      }
-    } else if (autoScroll() && scrollToBottomOnActivate()) {
-      dispatchFollowEvent({ type: "jump-bottom", immediate: true, explicit: false })
+      if (initialScrollToBottom()) scrollToBottom(true)
+      return
     }
+    if (autoScroll() && scrollToBottomOnActivate()) scrollToBottom(true)
   }))
 
   onCleanup(() => {
-    if (pendingContentRenderedFrame !== null && typeof cancelAnimationFrame === "function") {
-      cancelAnimationFrame(pendingContentRenderedFrame)
-      pendingContentRenderedFrame = null
-    }
-    if (pendingBottomFollowIntentFrame !== null && typeof cancelAnimationFrame === "function") {
-      cancelAnimationFrame(pendingBottomFollowIntentFrame)
-      pendingBottomFollowIntentFrame = null
-    }
+    invalidateScrollRestore()
+    if (pendingContentRenderedFrame !== null) cancelAnimationFrame(pendingContentRenderedFrame)
+    if (pendingExplicitBottomPinFrame !== null) cancelAnimationFrame(pendingExplicitBottomPinFrame)
     detachScrollIntentListeners?.()
-    detachScrollIntentListeners = undefined
   })
 
   return (
@@ -1187,6 +740,7 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
     }}>
       <div
         class="message-stream"
+        tabIndex={-1}
         ref={el => {
           setScrollElement(el)
           props.onScrollElementChange?.(el)
@@ -1195,9 +749,7 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
         onMouseUp={props.onMouseUp}
         onClick={props.onClick}
       >
-        <Show when={props.renderBeforeItems}>
-          {props.renderBeforeItems!()}
-        </Show>
+        <Show when={props.renderBeforeItems}>{props.renderBeforeItems!()}</Show>
         <Virtualizer
           ref={setVirtuaHandle}
           scrollRef={scrollElement()}
@@ -1207,12 +759,7 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
         >
           {(item, index) => {
             const key = props.getKey(item, index())
-            const anchorId = getAnchorIdForKey(key)
-            return (
-              <div id={anchorId} data-virtual-follow-key={key} ref={(element) => registerItemElement(key, element)}>
-                {props.renderItem(item, index())}
-              </div>
-            )
+            return <div id={getAnchorIdForKey(key)} data-virtual-follow-key={key} ref={(element) => registerItemElement(key, element)}>{props.renderItem(item, index())}</div>
           }}
         </Virtualizer>
       </div>
@@ -1225,27 +772,16 @@ export default function VirtualFollowList<T>(props: VirtualFollowListProps<T>) {
         <div class="virtual-follow-list-controls-container">{props.renderControls!(state, api)}</div>
       </Show>
 
-      <Show
-        when={
-          !props.renderControls &&
-          (showScrollTopButton() || showScrollBottomButton()) &&
-          props.scrollToTopAriaLabel &&
-          props.scrollToBottomAriaLabel
-        }
-      >
+      <Show when={!props.renderControls && (showScrollTopButton() || showScrollBottomButton()) && props.scrollToTopAriaLabel && props.scrollToBottomAriaLabel}>
         <div class="message-scroll-button-wrapper">
           <Show when={showScrollTopButton()}>
             <button type="button" class="message-scroll-button" onClick={() => scrollToTop()} aria-label={props.scrollToTopAriaLabel!()}>
-              <span class="message-scroll-icon" aria-hidden="true">
-                ↑
-              </span>
+              <span class="message-scroll-icon" aria-hidden="true">↑</span>
             </button>
           </Show>
           <Show when={showScrollBottomButton()}>
-            <button type="button" class="message-scroll-button" onClick={() => scrollToBottom(true, { suppressHold: true })} aria-label={props.scrollToBottomAriaLabel!()}>
-              <span class="message-scroll-icon" aria-hidden="true">
-                ↓
-              </span>
+            <button type="button" class="message-scroll-button" onClick={() => scrollToBottom(true)} aria-label={props.scrollToBottomAriaLabel!()}>
+              <span class="message-scroll-icon" aria-hidden="true">↓</span>
             </button>
           </Show>
         </div>
diff --git a/packages/ui/src/lib/api-client.ts b/packages/ui/src/lib/api-client.ts
index 353360ea..e94fd39b 100644
--- a/packages/ui/src/lib/api-client.ts
+++ b/packages/ui/src/lib/api-client.ts
@@ -11,17 +11,22 @@ import type {
   FileSystemFileContentResponse,
   FileSystemListResponse,
   InstanceData,
+  OpenCodeUpdateResponse,
+  OpenCodeUpdateStatus,
   SpeechCapabilitiesResponse,
   SpeechSynthesisResponse,
   SpeechTranscriptionResponse,
   SideCar,
   PreviewSession,
+  ProviderUsageResponse,
   ServerMeta,
+  SessionMetadataResponse,
   RemoteProxySessionCreateRequest,
   RemoteProxySessionCreateResponse,
   RemoteServerProbeRequest,
   RemoteServerProbeResponse,
   VoiceModeStateResponse,
+  YoloStateResponse,
   WorkspaceCloneRequest,
   WorkspaceCloneResponse,
   WorktreeGitCommitRequest,
@@ -30,6 +35,7 @@ import type {
   WorktreeGitMutationResponse,
   WorktreeGitPathsRequest,
   WorkspaceCreateRequest,
+  WorkspaceCreateResponse,
   WorkspaceDescriptor,
   WorkspaceFileResponse,
   WorkspaceFileSearchResponse,
@@ -192,6 +198,13 @@ export const serverApi = {
     return request<WorkspaceDescriptor[]>("/api/workspaces")
   },
 
+  fetchProviderUsage(providerId: string, modelId?: string): Promise<ProviderUsageResponse> {
+    const params = new URLSearchParams()
+    if (modelId) params.set("modelId", modelId)
+    const query = params.toString()
+    return request<ProviderUsageResponse>(`/api/usage/${encodeURIComponent(providerId)}${query ? `?${query}` : ""}`)
+  },
+
   fetchWorktrees(id: string): Promise<WorktreeListResponse> {
     return request<WorktreeListResponse>(`/api/workspaces/${encodeURIComponent(id)}/worktrees`)
   },
@@ -224,10 +237,23 @@ export const serverApi = {
       body: JSON.stringify(map),
     })
   },
-  createWorkspace(payload: WorkspaceCreateRequest): Promise<WorkspaceDescriptor> {
-    return request<WorkspaceDescriptor>("/api/workspaces", {
+  createWorkspace(payload: WorkspaceCreateRequest, options?: { signal?: AbortSignal }): Promise<WorkspaceCreateResponse> {
+    return request<WorkspaceCreateResponse>("/api/workspaces", {
       method: "POST",
       body: JSON.stringify(payload),
+      signal: options?.signal,
+    })
+  },
+  cancelWorkspaceCreation(requestId: string): Promise<void> {
+    return request("/api/workspaces/creation/cancel", {
+      method: "POST",
+      body: JSON.stringify({ requestId }),
+    })
+  },
+  releaseWorkspaceCreation(id: string, requestId: string): Promise<void> {
+    return request(`/api/workspaces/${encodeURIComponent(id)}/creation/release`, {
+      method: "POST",
+      body: JSON.stringify({ requestId }),
     })
   },
   fetchSidecars(): Promise<{ sidecars: SideCar[] }> {
@@ -428,6 +454,12 @@ export const serverApi = {
       body: JSON.stringify({ path }),
     })
   },
+  fetchOpenCodeUpdateStatus(): Promise<OpenCodeUpdateStatus> {
+    return request<OpenCodeUpdateStatus>("/api/opencode/update")
+  },
+  updateOpenCode(): Promise<OpenCodeUpdateResponse> {
+    return request<OpenCodeUpdateResponse>("/api/opencode/update", { method: "POST" })
+  },
   fetchSpeechCapabilities(): Promise<SpeechCapabilitiesResponse> {
     return request<SpeechCapabilitiesResponse>("/api/speech/capabilities")
   },
@@ -520,6 +552,23 @@ export const serverApi = {
       body: JSON.stringify({ ...identity, enabled }),
     })
   },
+  getYoloState(instanceId: string, sessionId: string): Promise<YoloStateResponse> {
+    return request<YoloStateResponse>(
+      `/workspaces/${encodeURIComponent(instanceId)}/yolo/sessions/${encodeURIComponent(sessionId)}`,
+    )
+  },
+  toggleYolo(instanceId: string, sessionId: string): Promise<YoloStateResponse> {
+    return request<YoloStateResponse>(
+      `/workspaces/${encodeURIComponent(instanceId)}/yolo/sessions/${encodeURIComponent(sessionId)}/toggle`,
+      { method: "POST" },
+    )
+  },
+  setSessionWorktreeSlug(instanceId: string, sessionId: string, worktreeSlug: string): Promise<SessionMetadataResponse> {
+    return request<SessionMetadataResponse>(
+      `/api/workspaces/${encodeURIComponent(instanceId)}/worktrees/sessions/${encodeURIComponent(sessionId)}`,
+      { method: "PUT", body: JSON.stringify({ worktreeSlug }) },
+    )
+  },
   sendClientConnectionPong(payload: { clientId: string; connectionId: string; pingTs?: number }, signal?: AbortSignal): Promise<void> {
     const init: RequestInit = {
       method: "POST",
diff --git a/packages/ui/src/lib/attachment-mentions.test.ts b/packages/ui/src/lib/attachment-mentions.test.ts
new file mode 100644
index 00000000..21e91602
--- /dev/null
+++ b/packages/ui/src/lib/attachment-mentions.test.ts
@@ -0,0 +1,27 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { createPromptMentionRegex, getAttachmentPromptMentionCandidates } from "./attachment-mentions.ts"
+
+describe("attachment prompt mentions", () => {
+  it("derives the relative directory token emitted by the runtime picker", () => {
+    assert.deepEqual(
+      getAttachmentPromptMentionCandidates({
+        display: "@nested/",
+        filename: "nested/",
+        source: { type: "file", path: "./dir/nested", mime: "inode/directory" },
+      }),
+      ["nested/", "./dir/nested", "./dir/nested/", "dir/nested/"],
+    )
+  })
+
+  it("matches literal spaced and regex-significant paths without consuming prefixes", () => {
+    const candidate = "C:\\work\\my file [draft](1).ts"
+    const prompt = `remove @${candidate} keep @${candidate}.bak and @other`
+
+    assert.equal(
+      prompt.replace(createPromptMentionRegex(candidate, { global: true }), ""),
+      `remove  keep @${candidate}.bak and @other`,
+    )
+  })
+})
diff --git a/packages/ui/src/lib/attachment-mentions.ts b/packages/ui/src/lib/attachment-mentions.ts
new file mode 100644
index 00000000..dc2c4cd7
--- /dev/null
+++ b/packages/ui/src/lib/attachment-mentions.ts
@@ -0,0 +1,53 @@
+import { createAttachmentPlaceholderRegex, getAttachmentPlaceholder } from "./attachment-placeholders"
+
+const MAX_MENTION_LENGTH = 4096
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+export function getAttachmentPromptMentionCandidates(value: unknown): string[] {
+  if (!isRecord(value)) return []
+  const source = isRecord(value.source) ? value.source : {}
+  const candidates: unknown[] = [
+    typeof value.display === "string" && value.display.startsWith("@") ? value.display.slice(1) : undefined,
+  ]
+
+  if (source.type === "file") {
+    candidates.push(source.path, value.filename)
+    if (source.mime === "inode/directory" && typeof source.path === "string") {
+      const path = source.path.replace(/\/+$/, "")
+      candidates.push(path === "" || path === "." ? "./" : `${path}/`)
+      if (path !== "" && path !== ".") candidates.push(`${path.replace(/^\.\//, "")}/`)
+    }
+  } else if (source.type === "agent") {
+    candidates.push(source.name, value.filename)
+  } else if (
+    source.type === "text" &&
+    typeof source.value === "string" &&
+    value.display === `path: ${source.value}`
+  ) {
+    candidates.push(source.value)
+  }
+
+  return [...new Set(candidates.filter(
+    (candidate): candidate is string =>
+      typeof candidate === "string" && candidate.length > 0 && candidate.length <= MAX_MENTION_LENGTH,
+  ))]
+}
+
+export function createPromptMentionRegex(candidate: string, options: { global?: boolean } = {}): RegExp {
+  // Picker paths are inserted literally, including spaces; escaping is only for regex matching.
+  return new RegExp(`@${escapeRegExp(candidate)}(?=\\s|$)`, options.global ? "gi" : "i")
+}
+
+export function removeAttachmentPromptTokens(prompt: string, attachment: unknown): string {
+  const display = isRecord(attachment) ? attachment.display : undefined
+  const placeholder = getAttachmentPlaceholder(display)
+  if (placeholder) {
+    return prompt.replace(createAttachmentPlaceholderRegex(placeholder.kind, placeholder.counter), "")
+  }
+  for (const candidate of getAttachmentPromptMentionCandidates(attachment)) {
+    prompt = prompt.replace(createPromptMentionRegex(candidate, { global: true }), "")
+  }
+  return prompt
+}
diff --git a/packages/ui/src/lib/attachment-placeholders.ts b/packages/ui/src/lib/attachment-placeholders.ts
new file mode 100644
index 00000000..500943c0
--- /dev/null
+++ b/packages/ui/src/lib/attachment-placeholders.ts
@@ -0,0 +1,23 @@
+export type AttachmentPlaceholderKind = "image" | "pasted"
+
+const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+export function getAttachmentPlaceholder(display: unknown) {
+  if (typeof display !== "string" || display.length > 1024) return
+  const match = display.match(/(pasted|image)\s*#\s*(\d+)/i)
+  if (!match) return
+  return {
+    kind: match[1]!.toLowerCase() === "image" ? "image" as const : "pasted" as const,
+    counter: match[2]!,
+  }
+}
+
+export function createAttachmentPlaceholderRegex(
+  kind: AttachmentPlaceholderKind,
+  counter: string | number | undefined = undefined,
+  options: { global?: boolean } = {},
+): RegExp {
+  const label = kind === "image" ? "Image" : "pasted"
+  const count = counter === undefined ? "(\\d+)" : escapeRegExp(String(counter))
+  return new RegExp(`\\[\\s*${label}\\s*#\\s*${count}\\s*\\]`, options.global === false ? "i" : "gi")
+}
diff --git a/packages/ui/src/lib/audio-utils.ts b/packages/ui/src/lib/audio-utils.ts
new file mode 100644
index 00000000..7701e723
--- /dev/null
+++ b/packages/ui/src/lib/audio-utils.ts
@@ -0,0 +1,21 @@
+export async function blobToBase64(blob: Blob): Promise<string> {
+  const buffer = await blob.arrayBuffer()
+  const bytes = new Uint8Array(buffer)
+  let binary = ""
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte)
+  }
+  return btoa(binary)
+}
+
+export function createMediaRecorder(stream: MediaStream): MediaRecorder {
+  const candidates = ["audio/webm;codecs=opus", "audio/webm", "audio/mp4", "audio/ogg;codecs=opus"]
+  const supported = candidates.find(
+    (candidate) => typeof MediaRecorder.isTypeSupported !== "function" || MediaRecorder.isTypeSupported(candidate),
+  )
+  return supported ? new MediaRecorder(stream, { mimeType: supported }) : new MediaRecorder(stream)
+}
+
+export function stopTracks(stream: MediaStream | null) {
+  stream?.getTracks().forEach((track) => track.stop())
+}
diff --git a/packages/ui/src/lib/connection-status.test.ts b/packages/ui/src/lib/connection-status.test.ts
new file mode 100644
index 00000000..84319e2a
--- /dev/null
+++ b/packages/ui/src/lib/connection-status.test.ts
@@ -0,0 +1,38 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { deriveDisplayConnectionStatus, seedConnectionStatusIfMissing } from "./connection-status.ts"
+
+describe("deriveDisplayConnectionStatus", () => {
+  it("overlays connecting while transport is down for connected instances", () => {
+    assert.equal(deriveDisplayConnectionStatus("connected", "disconnected"), "connecting")
+  })
+
+  it("restores previous connected status when transport reconnects", () => {
+    assert.equal(deriveDisplayConnectionStatus("connected", "connected"), "connected")
+  })
+
+  it("preserves disconnected instance status while transport is down", () => {
+    assert.equal(deriveDisplayConnectionStatus("disconnected", "disconnected"), "disconnected")
+  })
+
+  it("preserves error instance status while transport is down", () => {
+    assert.equal(deriveDisplayConnectionStatus("error", "disconnected"), "error")
+  })
+
+  it("does not clear legitimate instance connecting status after transport opens", () => {
+    assert.equal(deriveDisplayConnectionStatus("connecting", "connected"), "connecting")
+  })
+})
+
+describe("seedConnectionStatusIfMissing", () => {
+  it("does not overwrite a connected status received before client attachment", () => {
+    const connected = new Map([["workspace-1", "connected" as const]])
+    assert.equal(seedConnectionStatusIfMissing(connected, "workspace-1", "connecting"), connected)
+    assert.equal(connected.get("workspace-1"), "connected")
+  })
+
+  it("seeds connecting when no stream status has arrived", () => {
+    const seeded = seedConnectionStatusIfMissing(new Map(), "workspace-1", "connecting")
+    assert.equal(seeded.get("workspace-1"), "connecting")
+  })
+})
diff --git a/packages/ui/src/lib/connection-status.ts b/packages/ui/src/lib/connection-status.ts
new file mode 100644
index 00000000..ce237a7b
--- /dev/null
+++ b/packages/ui/src/lib/connection-status.ts
@@ -0,0 +1,30 @@
+import type { InstanceStreamStatus } from "../../../server/src/api-types"
+import type { WorkspaceEventTransportStatus } from "./event-transport"
+
+export type ConnectionStatus = InstanceStreamStatus
+
+export function seedConnectionStatusIfMissing(
+  statuses: Map<string, ConnectionStatus>,
+  instanceId: string,
+  status: ConnectionStatus,
+): Map<string, ConnectionStatus> {
+  if (statuses.has(instanceId)) return statuses
+  const next = new Map(statuses)
+  next.set(instanceId, status)
+  return next
+}
+
+export function deriveDisplayConnectionStatus(
+  instanceStatus: ConnectionStatus | null,
+  workspaceTransportStatus: WorkspaceEventTransportStatus,
+): ConnectionStatus | null {
+  if (instanceStatus === "disconnected" || instanceStatus === "error") {
+    return instanceStatus
+  }
+
+  if (workspaceTransportStatus !== "connected") {
+    return "connecting"
+  }
+
+  return instanceStatus
+}
diff --git a/packages/ui/src/lib/event-transport.ts b/packages/ui/src/lib/event-transport.ts
index 24b69591..5de633c3 100644
--- a/packages/ui/src/lib/event-transport.ts
+++ b/packages/ui/src/lib/event-transport.ts
@@ -15,9 +15,12 @@ export interface WorkspaceEventTransportCallbacks {
   onBatch: (events: WorkspaceEventPayload[]) => void
   onError?: () => void
   onOpen?: () => void
+  onStatus?: (status: WorkspaceEventTransportStatus) => void
   onPing?: (payload: { ts?: number }) => void
 }
 
+export type WorkspaceEventTransportStatus = "connecting" | "connected" | "disconnected"
+
 export interface WorkspaceEventConnection {
   disconnect: () => void
 }
@@ -25,10 +28,17 @@ export interface WorkspaceEventConnection {
 async function connectBrowserWorkspaceEvents(
   callbacks: WorkspaceEventTransportCallbacks,
 ): Promise<WorkspaceEventConnection> {
+  const notifyDisconnected = () => {
+    callbacks.onStatus?.("disconnected")
+    callbacks.onError?.()
+  }
   const source = serverApi.connectEvents((event) => {
     callbacks.onBatch([event])
-  }, callbacks.onError, callbacks.onPing)
-  source.onopen = () => callbacks.onOpen?.()
+  }, notifyDisconnected, callbacks.onPing)
+  source.onopen = () => {
+    callbacks.onStatus?.("connected")
+    callbacks.onOpen?.()
+  }
   return {
     disconnect() {
       source.close()
diff --git a/packages/ui/src/lib/follow-scroll.tsx b/packages/ui/src/lib/follow-scroll.tsx
index 89b489a9..34c40724 100644
--- a/packages/ui/src/lib/follow-scroll.tsx
+++ b/packages/ui/src/lib/follow-scroll.tsx
@@ -1,4 +1,5 @@
 import { createEffect, createSignal, onCleanup, type Accessor, type JSXElement } from "solid-js"
+import { BOTTOM_FOLLOW_EPSILON_PX, VirtualScrollController, isAutoFollowing, type ScrollControllerMetrics } from "../components/virtual-follow-behavior"
 
 const DEFAULT_SCROLL_INTENT_WINDOW_MS = 600
 const DEFAULT_SCROLL_INTENT_KEYS = new Set(["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " ", "Spacebar"])
@@ -6,7 +7,6 @@ const DEFAULT_SCROLL_INTENT_KEYS = new Set(["ArrowUp", "ArrowDown", "PageUp", "P
 interface FollowScrollOptions {
   getScrollTopSnapshot: Accessor<number>
   setScrollTopSnapshot: (next: number) => void
-  sentinelMarginPx: number
   sentinelClassName: string
   intentWindowMs?: number
   intentKeys?: ReadonlySet<string>
@@ -24,16 +24,14 @@ export function createFollowScroll(options: FollowScrollOptions): FollowScrollHe
   const [scrollContainer, setScrollContainer] = createSignal<HTMLDivElement | undefined>()
   const [bottomSentinel, setBottomSentinel] = createSignal<HTMLDivElement | null>(null)
   const [autoScroll, setAutoScroll] = createSignal(true)
-  const [bottomSentinelVisible, setBottomSentinelVisible] = createSignal(true)
+  const scrollController = new VirtualScrollController(true)
 
   let scrollContainerRef: HTMLDivElement | undefined
   let detachScrollIntentListeners: (() => void) | undefined
 
   let pendingScrollFrame: number | null = null
   let pendingAnchorScroll: number | null = null
-  let userScrollIntentUntil = 0
   let lastKnownScrollTop = options.getScrollTopSnapshot()
-  let pointerInteractionActive = false
   let suppressNextScrollHandling = false
 
   function restoreScrollPosition(forceBottom = false) {
@@ -44,8 +42,10 @@ export function createFollowScroll(options: FollowScrollOptions): FollowScrollHe
       container.scrollTop = container.scrollHeight
       lastKnownScrollTop = container.scrollTop
       options.setScrollTopSnapshot(lastKnownScrollTop)
+      scrollController.recordProgrammaticOffset(lastKnownScrollTop, true)
     } else {
       container.scrollTop = lastKnownScrollTop
+      scrollController.recordProgrammaticOffset(lastKnownScrollTop, isAtBottom(container))
     }
   }
 
@@ -55,17 +55,9 @@ export function createFollowScroll(options: FollowScrollOptions): FollowScrollHe
     options.setScrollTopSnapshot(lastKnownScrollTop)
   }
 
-  function markUserScrollIntent() {
+  function markUserScrollIntent(direction: "up" | "down" | null) {
     const now = typeof performance !== "undefined" ? performance.now() : Date.now()
-    userScrollIntentUntil = now + (options.intentWindowMs ?? DEFAULT_SCROLL_INTENT_WINDOW_MS)
-  }
-
-  function hasUserScrollIntent() {
-    if (pointerInteractionActive) {
-      return true
-    }
-    const now = typeof performance !== "undefined" ? performance.now() : Date.now()
-    return now <= userScrollIntentUntil
+    scrollController.setUserIntent(direction, now + (options.intentWindowMs ?? DEFAULT_SCROLL_INTENT_WINDOW_MS))
   }
 
   function attachScrollIntentListeners(element: HTMLDivElement) {
@@ -74,42 +66,27 @@ export function createFollowScroll(options: FollowScrollOptions): FollowScrollHe
       detachScrollIntentListeners = undefined
     }
     const intentKeys = options.intentKeys ?? DEFAULT_SCROLL_INTENT_KEYS
-    const handlePointerIntent = () => {
-      pointerInteractionActive = true
-      markUserScrollIntent()
-    }
-    const clearPointerIntent = () => {
-      pointerInteractionActive = false
+    const handlePointerIntent = (event: WheelEvent | PointerEvent | TouchEvent) => {
+      markUserScrollIntent(event instanceof WheelEvent ? (event.deltaY < 0 ? "up" : event.deltaY > 0 ? "down" : null) : null)
     }
     const handleKeyIntent = (event: KeyboardEvent) => {
       if (intentKeys.has(event.key)) {
-        markUserScrollIntent()
+        const direction =
+          event.key === "ArrowUp" || event.key === "PageUp" || event.key === "Home" || (event.shiftKey && (event.key === " " || event.key === "Spacebar"))
+            ? "up"
+            : "down"
+        markUserScrollIntent(direction)
       }
     }
     element.addEventListener("wheel", handlePointerIntent, { passive: true })
     element.addEventListener("pointerdown", handlePointerIntent)
     element.addEventListener("touchstart", handlePointerIntent, { passive: true })
     element.addEventListener("keydown", handleKeyIntent)
-    if (typeof window !== "undefined") {
-      window.addEventListener("pointerup", clearPointerIntent)
-      window.addEventListener("pointercancel", clearPointerIntent)
-      window.addEventListener("mouseup", clearPointerIntent)
-      window.addEventListener("touchend", clearPointerIntent)
-      window.addEventListener("touchcancel", clearPointerIntent)
-    }
     detachScrollIntentListeners = () => {
       element.removeEventListener("wheel", handlePointerIntent)
       element.removeEventListener("pointerdown", handlePointerIntent)
       element.removeEventListener("touchstart", handlePointerIntent)
       element.removeEventListener("keydown", handleKeyIntent)
-      if (typeof window !== "undefined") {
-        window.removeEventListener("pointerup", clearPointerIntent)
-        window.removeEventListener("pointercancel", clearPointerIntent)
-        window.removeEventListener("mouseup", clearPointerIntent)
-        window.removeEventListener("touchend", clearPointerIntent)
-        window.removeEventListener("touchcancel", clearPointerIntent)
-      }
-      pointerInteractionActive = false
     }
   }
 
@@ -126,18 +103,28 @@ export function createFollowScroll(options: FollowScrollOptions): FollowScrollHe
       pendingAnchorScroll = null
       const containerRect = container.getBoundingClientRect()
       const sentinelRect = sentinel.getBoundingClientRect()
-      const delta = sentinelRect.bottom - containerRect.bottom + options.sentinelMarginPx
+      const delta = sentinelRect.bottom - containerRect.bottom
       if (Math.abs(delta) > 1) {
         suppressNextScrollHandling = true
         container.scrollBy({ top: delta, behavior: immediate ? "auto" : "smooth" })
       }
       lastKnownScrollTop = container.scrollTop
       options.setScrollTopSnapshot(lastKnownScrollTop)
+      scrollController.recordProgrammaticOffset(lastKnownScrollTop, isAtBottom(container))
     })
   }
 
+  function getMetrics(container: HTMLDivElement): ScrollControllerMetrics {
+    return {
+      offset: container.scrollTop,
+      scrollHeight: container.scrollHeight,
+      clientHeight: container.clientHeight,
+      sentinelMarginPx: BOTTOM_FOLLOW_EPSILON_PX,
+    }
+  }
+
   function isAtBottom(container: HTMLDivElement) {
-    return container.scrollHeight - (container.scrollTop + container.clientHeight) <= options.sentinelMarginPx
+    return container.scrollHeight - (container.scrollTop + container.clientHeight) <= BOTTOM_FOLLOW_EPSILON_PX
   }
 
   function updateFollowModeFromScroll(containerOverride?: HTMLDivElement) {
@@ -147,17 +134,8 @@ export function createFollowScroll(options: FollowScrollOptions): FollowScrollHe
       suppressNextScrollHandling = false
       return
     }
-    const isUserScroll = hasUserScrollIntent()
-    const atBottomFromScroll = isAtBottom(container)
-    const atBottom = atBottomFromScroll || bottomSentinelVisible()
-
-    if (isUserScroll || !atBottom) {
-      if (atBottom) {
-        if (!autoScroll()) setAutoScroll(true)
-      } else if (autoScroll()) {
-        setAutoScroll(false)
-      }
-    }
+    const result = scrollController.observeViewport(getMetrics(container), typeof performance !== "undefined" ? performance.now() : Date.now(), false)
+    setAutoScroll(isAutoFollowing(result.state.mode))
   }
 
   const handleScroll = (event: Event & { currentTarget: HTMLDivElement }) => {
@@ -166,7 +144,7 @@ export function createFollowScroll(options: FollowScrollOptions): FollowScrollHe
   }
 
   const registerContainer = (element: HTMLDivElement | null | undefined, config?: { disableTracking?: boolean }) => {
-    const next = element || undefined
+    const next = config?.disableTracking ? undefined : element || undefined
     if (next === scrollContainerRef) {
       return
     }
@@ -185,10 +163,13 @@ export function createFollowScroll(options: FollowScrollOptions): FollowScrollHe
 
   const restoreAfterRender = () => {
     const container = scrollContainerRef
-    if (container && hasUserScrollIntent() && !isAtBottom(container)) {
-      if (autoScroll()) {
-        setAutoScroll(false)
-      }
+    if (!container) return
+
+    const now = typeof performance !== "undefined" ? performance.now() : Date.now()
+    const result = scrollController.observeViewport(getMetrics(container), now, false)
+    setAutoScroll(isAutoFollowing(result.state.mode))
+    const hasFreshUpwardEscape = now <= result.state.userIntentUntil && result.state.userIntentDirection === "up" && result.state.mode.type === "escaped"
+    if (hasFreshUpwardEscape) {
       requestAnimationFrame(() => {
         restoreScrollPosition(false)
       })
@@ -219,24 +200,6 @@ export function createFollowScroll(options: FollowScrollOptions): FollowScrollHe
     })
   })
 
-  createEffect(() => {
-    const container = scrollContainer()
-    const sentinel = bottomSentinel()
-    if (!container || !sentinel) return
-    const observer = new IntersectionObserver(
-      (entries) => {
-        entries.forEach((entry) => {
-          if (entry.target === sentinel) {
-            setBottomSentinelVisible(entry.isIntersecting)
-          }
-        })
-      },
-      { root: container, threshold: 0, rootMargin: `0px 0px ${options.sentinelMarginPx}px 0px` },
-    )
-    observer.observe(sentinel)
-    onCleanup(() => observer.disconnect())
-  })
-
   onCleanup(() => {
     if (pendingScrollFrame !== null) {
       cancelAnimationFrame(pendingScrollFrame)
diff --git a/packages/ui/src/lib/hooks/use-app-session-capture.test.ts b/packages/ui/src/lib/hooks/use-app-session-capture.test.ts
new file mode 100644
index 00000000..b644b0fd
--- /dev/null
+++ b/packages/ui/src/lib/hooks/use-app-session-capture.test.ts
@@ -0,0 +1,37 @@
+import assert from "node:assert/strict"
+import { readFileSync } from "node:fs"
+import { describe, it } from "node:test"
+
+const source = (file: string) => readFileSync(new URL(file, import.meta.url), "utf8")
+
+describe("app session capture listener readiness", () => {
+  it("waits for both Tauri flush listeners before restore starts capture", () => {
+    const capture = source("./use-app-session-capture.ts")
+    const restore = source("./use-app-session-restore.ts")
+    const ready = capture.slice(capture.indexOf("const ready ="), capture.indexOf("const markScrollAuthority"))
+    assert.match(ready, /Promise\.all/)
+    assert.match(ready, /client-state:flush-requested/)
+    assert.match(ready, /client-state:navigation-flush-requested/)
+    assert.ok(restore.indexOf("await capture.ready") < restore.indexOf("capture.start("))
+  })
+
+  it("uses the serialized commit queue without serializing create requests", () => {
+    const restore = source("./use-app-session-restore.ts")
+    assert.match(restore, /runWithSerializedCommits/)
+    assert.match(restore, /waitForCreateCommit/)
+    assert.doesNotMatch(restore, /for \(const match of missing\) await restoreWorkspace/)
+  })
+
+  it("does not track prompt hydration writes in the capture effect", () => {
+    const capture = source("./use-app-session-capture.ts")
+    assert.match(capture, /untrack\(\(\) => hydratePreservedPrompts/)
+  })
+
+  it("reapplies full preserved state after transient reopen hydration", () => {
+    const capture = source("./use-app-session-capture.ts")
+    assert.match(capture, /waitForInstanceInitialSessionHydration/)
+    assert.match(capture, /hydrateRestoredWorkspaceState/)
+    assert.match(capture, /settlePreservedTab/)
+  })
+
+})
diff --git a/packages/ui/src/lib/hooks/use-app-session-capture.ts b/packages/ui/src/lib/hooks/use-app-session-capture.ts
new file mode 100644
index 00000000..3e21446f
--- /dev/null
+++ b/packages/ui/src/lib/hooks/use-app-session-capture.ts
@@ -0,0 +1,316 @@
+import { createEffect, createSignal, onCleanup, onMount, untrack } from "solid-js"
+import { listen } from "@tauri-apps/api/event"
+import { getLogger } from "../logger"
+import { acknowledgeNativeClientStateNavigationFlush, acknowledgeNativeClientStateRendererFlush } from "../native/client-state"
+import { isElectronHost, isLocalWindow, isTauriHost } from "../runtime-env"
+import {
+  clientStateIsPrimary, flushClientState, restorePreviousStateEnabled, updateRestorableSession,
+  type RestorableSessionState, type RestorableTabState, type RestorableWorkspaceTabState,
+} from "../../stores/client-state"
+import { normalizeWorkspacePath } from "../../stores/app-session-reconciliation"
+import {
+  createRestorableSessionPreservation, createRestoredTabCommitGuard, markPreservedWorkspaceRemoved,
+  markPreservedWorkspaceReopened, markPreservedWorkspaceUnavailable,
+  getPreservedWorkspaceReopenTarget, getPreservedWorkspaceState,
+  hasRestoredTabBinding, mergeRestorableSessionState, recordRestoredTab,
+  settleRestoredTab as settlePreservedTab, type RestorableSessionPreservation,
+  type RestorableWorkspaceRuntimeAuthority,
+} from "../../stores/app-session-snapshot-merge"
+import { activeAppTabId, appTabs, getInstanceAppTabId } from "../../stores/app-tabs"
+import { showFolderSelection } from "../../stores/ui"
+import { instances, waitForInstanceInitialSessionHydration } from "../../stores/instances"
+import {
+  activeParentSessionId, activeSessionId, expandedSessions, getAuthoritativeDraftSessionIdsForInstance,
+  getAuthoritativeSessionExpansionIdsForInstance, getAuthoritativelyDeletedSessionIdsForInstance,
+  getSessionDraftPromptsForInstance, getSessions,
+  hasAuthoritativeSessionSelection,
+} from "../../stores/sessions"
+import { messageStoreBus } from "../../stores/message-v2/bus"
+import type { ScrollSnapshot } from "../../stores/message-v2/types"
+import { getAuthoritativeAttachmentSessionIdsForInstance, getSessionAttachmentsForInstance } from "../../stores/attachments"
+import { serializeDraftAttachments } from "../../stores/client-state-attachments-codec"
+import { onInstanceLifecycleAuthority } from "../../stores/instance-lifecycle-authority"
+import { getPersistedGenerationRecovery, type PersistedGenerationRecovery } from "../../stores/session-generation-recovery"
+import { hydrateWorkspacePromptState } from "../../stores/app-session-prompt-hydration"
+import {
+  hydrateRestoredWorkspaceState, NO_SESSION_DRAFT_SESSION_ID,
+} from "../../stores/app-session-workspace-hydration"
+const log = getLogger("actions")
+const MESSAGE_SCROLL_SCOPE = "message-stream"
+const MAX_CAPTURED_SCROLL_SNAPSHOTS = 96
+const CAPTURE_DEBOUNCE_MS = 100
+function captureScrollSnapshots(instanceId: string): Record<string, ScrollSnapshot> {
+  const store = messageStoreBus.getInstance(instanceId)
+  if (!store) return {}
+  const suffix = `:${MESSAGE_SCROLL_SCOPE}`
+  return Object.fromEntries(Object.entries(store.state.scrollState)
+    .filter(([key]) => key.endsWith(suffix))
+    .map(([key, snapshot]) => ({ sessionId: key.slice(0, -suffix.length), snapshot }))
+    .filter(({ sessionId }) => Boolean(sessionId))
+    .sort((a, b) => b.snapshot.updatedAt - a.snapshot.updatedAt)
+    .slice(0, MAX_CAPTURED_SCROLL_SNAPSHOTS)
+    .map(({ sessionId, snapshot }) => [sessionId, { ...snapshot }]))
+}
+function captureRuntimeState(instanceId: string): Pick<RestorableWorkspaceTabState, "unseenIdleSince" | "generationRecovery"> {
+  const unseenIdleSince: Record<string, number> = {}
+  const generationRecovery: Record<string, PersistedGenerationRecovery> = {}
+  for (const session of getSessions(instanceId)) {
+    if (session.status === "idle" && typeof session.idleSince === "number") unseenIdleSince[session.id] = session.idleSince
+    const recovery = getPersistedGenerationRecovery(session.status, session.generationRecovery)
+    if (recovery) generationRecovery[session.id] = recovery
+  }
+  return { unseenIdleSince, generationRecovery }
+}
+function captureState(scrollAuthority: ReadonlyMap<string, ReadonlySet<string>>) {
+  const tabs = appTabs()
+  const nextOccurrence = new Map<string, number>()
+  const occurrenceByInstance = new Map<string, number>()
+  for (const instance of instances().values()) {
+    const path = normalizeWorkspacePath(instance.folder)
+    const occurrence = nextOccurrence.get(path) ?? 0
+    nextOccurrence.set(path, occurrence + 1)
+    occurrenceByInstance.set(instance.id, occurrence)
+  }
+  const restorableTabs: RestorableTabState[] = tabs.map((tab) => {
+    if (tab.kind === "sidecar") return { kind: "sidecar", sidecarId: tab.sidecarTab.sidecarId }
+    const id = tab.instance.id
+    const parentId = activeParentSessionId().get(id)
+    const sessionId = activeSessionId().get(id)
+    const expansionAuthority = getAuthoritativeSessionExpansionIdsForInstance(id)
+    const expanded = [...(expandedSessions().get(id) ?? [])]
+    const prioritySessionIds = [sessionId, "__no_session_draft__"].filter((value): value is string => Boolean(value))
+    const result: RestorableWorkspaceTabState = {
+      kind: "workspace", folder: tab.instance.folder, occurrence: occurrenceByInstance.get(id) ?? 0,
+      ...serializeDraftAttachments(
+        getSessionDraftPromptsForInstance(id), getSessionAttachmentsForInstance(id), prioritySessionIds,
+      ),
+      ...captureRuntimeState(id), scrollSnapshots: captureScrollSnapshots(id),
+      expandedSessionIds: [
+        ...expanded.filter((sessionId) => expansionAuthority.has(sessionId)),
+        ...expanded.filter((sessionId) => !expansionAuthority.has(sessionId)),
+      ],
+    }
+    if (tab.instance.projectName) result.projectName = tab.instance.projectName
+    if (tab.instance.binaryPath) result.binaryPath = tab.instance.binaryPath
+    if (parentId) result.activeParentSessionId = parentId
+    if (sessionId) result.activeSessionId = sessionId
+    return result
+  })
+  const authorities: Array<RestorableWorkspaceRuntimeAuthority | undefined> = tabs.map((tab) => {
+    if (tab.kind !== "instance") return undefined
+    const id = tab.instance.id
+    const sessionIds = new Set(getSessions(id).map(({ id }) => id))
+    return {
+      drafts: getAuthoritativeDraftSessionIdsForInstance(id),
+      attachments: getAuthoritativeAttachmentSessionIdsForInstance(id),
+      scrollSnapshots: scrollAuthority.get(id), idleMarkers: sessionIds, generationRecovery: sessionIds,
+      sessionExpansion: getAuthoritativeSessionExpansionIdsForInstance(id),
+      deletedSessions: getAuthoritativelyDeletedSessionIdsForInstance(id),
+      sessionSelection: hasAuthoritativeSessionSelection(id),
+    }
+  })
+  return {
+    state: {
+      tabs: restorableTabs,
+      activeTabIndex: tabs.findIndex(({ id }) => id === activeAppTabId()),
+      ...(showFolderSelection() ? { homeActive: true } : {}),
+    },
+    tabIds: tabs.map(({ id }) => id), authorities,
+  }
+}
+export function useAppSessionCapture() {
+  const [started, setStarted] = createSignal(false)
+  const enabled = () => started() && clientStateIsPrimary() && restorePreviousStateEnabled()
+  const scrollAuthority = new Map<string, Set<string>>()
+  const instanceLifecycleTokens = new Map<string, number>()
+  let nextInstanceLifecycleToken = 0
+  let disposed = false
+  const hydrationController = new AbortController()
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let preservation: RestorableSessionPreservation | null = null
+  const hydratePreservedPrompts = (instanceId: string) => {
+    if (!preservation) return
+    const instance = instances().get(instanceId)
+    if (!instance) return
+    const snapshot = getPreservedWorkspaceState(preservation, {
+      runtimeTabId: getInstanceAppTabId(instanceId), folder: instance.folder, occurrence: 0,
+    })
+    if (!snapshot) return
+    hydrateWorkspacePromptState(
+      instanceId,
+      snapshot,
+      new Set(getSessions(instanceId).map(({ id }) => id)),
+      NO_SESSION_DRAFT_SESSION_ID,
+    )
+  }
+  const mergedState = () => {
+    const captured = captureState(scrollAuthority)
+    return mergeRestorableSessionState(captured.state, preservation, {
+      currentTabIds: captured.tabIds, currentTabAuthorities: captured.authorities,
+    })
+  }
+  const capture = () => {
+    timer = null
+    if (enabled() && !disposed) updateRestorableSession(mergedState())
+  }
+  const schedule = () => {
+    if (!enabled() || disposed) return
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(capture, CAPTURE_DEBOUNCE_MS)
+  }
+  const flush = async () => {
+    if (timer) clearTimeout(timer)
+    timer = null
+    if (enabled()) updateRestorableSession(mergedState())
+    await flushClientState()
+  }
+  const nativeUnlisteners: Array<() => void> = []
+  let nativeDisposed = false
+  const register = <T,>(event: string, acknowledge: (payload: T) => void | Promise<void>) => listen<T>(event, ({ payload }) => {
+    void flush().then(() => acknowledge(payload)).catch((error) => log.error(`Failed to handle ${event}`, error))
+  }).then((unlisten) => {
+    if (nativeDisposed) unlisten()
+    else nativeUnlisteners.push(unlisten)
+  }).catch((error) => log.error(`Failed to listen for ${event}`, error))
+  const ready = isTauriHost() && isLocalWindow()
+    ? Promise.all([
+        register<{ generation: number }>("client-state:flush-requested",
+          ({ generation }) => acknowledgeNativeClientStateRendererFlush(generation)),
+        register<{ generation: number }>("client-state:navigation-flush-requested",
+          ({ generation }) => acknowledgeNativeClientStateNavigationFlush(generation)),
+      ]).then(() => undefined)
+    : Promise.resolve()
+  const markScrollAuthority = (instanceId: string, sessionId: string) => {
+    const sessionIds = scrollAuthority.get(instanceId) ?? new Set<string>()
+    sessionIds.add(sessionId)
+    scrollAuthority.set(instanceId, sessionIds)
+    schedule()
+  }
+  const cleanups = [
+    messageStoreBus.onScrollSnapshotChanged((instanceId, sessionId, scope) => {
+      if (scope === MESSAGE_SCROLL_SCOPE) markScrollAuthority(instanceId, sessionId)
+    }),
+    messageStoreBus.onSessionCleared(markScrollAuthority),
+    messageStoreBus.onInstanceDestroyed((instanceId) => {
+      scrollAuthority.delete(instanceId)
+      instanceLifecycleTokens.delete(instanceId)
+    }),
+    onInstanceLifecycleAuthority((event) => {
+      const lifecycleToken = ++nextInstanceLifecycleToken
+      instanceLifecycleTokens.set(event.instanceId, lifecycleToken)
+      if (!preservation) return
+      const workspace = { runtimeTabId: getInstanceAppTabId(event.instanceId), folder: event.folder, occurrence: event.occurrence }
+      if (event.type === "unavailable") {
+        const captured = captureState(scrollAuthority)
+        const index = captured.tabIds.indexOf(workspace.runtimeTabId)
+        const tab = index < 0 ? undefined : captured.state.tabs[index]
+        markPreservedWorkspaceUnavailable(
+          preservation,
+          workspace,
+          tab?.kind === "workspace" ? tab : undefined,
+          index < 0 ? undefined : captured.authorities[index],
+        )
+        schedule()
+        return
+      }
+      if (event.type === "removed") {
+        markPreservedWorkspaceRemoved(preservation, workspace)
+      } else {
+        const target = getPreservedWorkspaceReopenTarget(preservation, workspace)
+        markPreservedWorkspaceReopened(preservation, workspace)
+        const snapshot = target?.snapshot
+        const sourceIndex = target?.sourceIndex ?? -1
+        const isCurrentBinding = () => Boolean(
+          preservation
+          && instanceLifecycleTokens.get(event.instanceId) === lifecycleToken
+          && instances().has(event.instanceId)
+          && hasRestoredTabBinding(preservation, sourceIndex, workspace.runtimeTabId),
+        )
+        if (snapshot && instances().has(event.instanceId)) void waitForInstanceInitialSessionHydration(event.instanceId).then(() => {
+          if (!isCurrentBinding()) return null
+          return hydrateRestoredWorkspaceState(event.instanceId, snapshot, hydrationController.signal, isCurrentBinding)
+        }).then((unavailable) => {
+          if (!unavailable || !preservation || !isCurrentBinding()) return
+          settlePreservedTab(preservation, sourceIndex, workspace.runtimeTabId, workspace.runtimeTabId, unavailable)
+          schedule()
+        }).catch((error) => {
+          if (!hydrationController.signal.aborted && isCurrentBinding()) {
+            log.warn("Failed to restore preserved state for reopened workspace", { instanceId: event.instanceId, error })
+          }
+        })
+      }
+      schedule()
+    }),
+  ]
+  createEffect(() => {
+    if (!enabled()) return
+    const tabs = appTabs()
+    activeAppTabId(); activeParentSessionId(); activeSessionId(); expandedSessions(); showFolderSelection()
+    for (const tab of tabs) if (tab.kind === "instance") {
+      getSessions(tab.instance.id)
+      getSessionDraftPromptsForInstance(tab.instance.id)
+      getSessionAttachmentsForInstance(tab.instance.id)
+    }
+    schedule()
+  })
+  createEffect(() => {
+    if (!enabled()) return
+    const tabs = appTabs()
+    for (const tab of tabs) if (tab.kind === "instance") {
+      getSessions(tab.instance.id)
+      untrack(() => hydratePreservedPrompts(tab.instance.id))
+    }
+  })
+  onMount(() => {
+    const flushNow = () => void flush()
+    window.addEventListener("pagehide", flushNow)
+    window.addEventListener("beforeunload", flushNow)
+    if (isElectronHost() && isLocalWindow()) window.__CODENOMAD_FLUSH_CLIENT_STATE_BEFORE_NATIVE_SHUTDOWN__ = flush
+    onCleanup(() => {
+      window.removeEventListener("pagehide", flushNow)
+      window.removeEventListener("beforeunload", flushNow)
+      if (window.__CODENOMAD_FLUSH_CLIENT_STATE_BEFORE_NATIVE_SHUTDOWN__ === flush) {
+        delete window.__CODENOMAD_FLUSH_CLIENT_STATE_BEFORE_NATIVE_SHUTDOWN__
+      }
+    })
+  })
+  onCleanup(() => {
+    hydrationController.abort(new Error("App session capture disposed"))
+    nativeDisposed = true
+    nativeUnlisteners.forEach((unlisten) => unlisten())
+    void flush()
+    disposed = true
+    cleanups.forEach((cleanup) => cleanup())
+  })
+  return {
+    ready,
+    start(snapshot?: RestorableSessionState) {
+      if (snapshot) preservation = createRestorableSessionPreservation(snapshot)
+      setStarted(true)
+    },
+    recordRestoredTab(index: number, tabId: string | null, unavailable?: ReadonlySet<string>) {
+      if (!preservation) return
+      recordRestoredTab(preservation, index, tabId, unavailable)
+      schedule()
+    },
+    createRestoredTabCommitGuard(index: number) {
+      return preservation ? createRestoredTabCommitGuard(preservation, index) : () => false
+    },
+    hasRestoredTabBinding(index: number, expectedRuntimeTabId: string) {
+      return preservation ? hasRestoredTabBinding(preservation, index, expectedRuntimeTabId) : false
+    },
+    settleRestoredTab(
+      index: number,
+      expectedRuntimeTabId: string,
+      tabId: string | null,
+      unavailable?: ReadonlySet<string>,
+    ) {
+      if (!preservation || !settlePreservedTab(preservation, index, expectedRuntimeTabId, tabId, unavailable)) return false
+      schedule()
+      return true
+    },
+    restoredTabIds: () => preservation?.results.map((result) =>
+      "runtimeTabId" in result ? result.runtimeTabId ?? null : null) ?? [],
+  }
+}
+export type AppSessionCaptureController = ReturnType<typeof useAppSessionCapture>
diff --git a/packages/ui/src/lib/hooks/use-app-session-restore.ts b/packages/ui/src/lib/hooks/use-app-session-restore.ts
new file mode 100644
index 00000000..2c748776
--- /dev/null
+++ b/packages/ui/src/lib/hooks/use-app-session-restore.ts
@@ -0,0 +1,228 @@
+import { onCleanup, onMount } from "solid-js"
+import { getLogger } from "../logger"
+import { isWebHost } from "../runtime-env"
+import { useAppSessionCapture, type AppSessionCaptureController } from "./use-app-session-capture"
+import {
+  clientStateIsPrimary, loadedRestorableSession, restorePreviousStateEnabled,
+  type RestorableSessionState,
+} from "../../stores/client-state"
+import { releaseAppSessionRestoreGate } from "../../stores/app-session-restore-gate"
+import { setShowFolderSelection } from "../../stores/ui"
+import {
+  reconcileWorkspaceTabs, resolveRestoredActiveTabId, shouldRestoreSessionState,
+} from "../../stores/app-session-reconciliation"
+import { getAbortReason, runAbortable } from "../../stores/app-session-restore-timeout"
+import {
+  activeAppTabId, appTabOrderRevision, appTabSelectionRevision, getInstanceAppTabId,
+  getSidecarAppTabId, selectAppTab, setAppTabOrder,
+} from "../../stores/app-tabs"
+import {
+  cancelRestoreCreationRequest, createInstance, disposeRestoreCreatedInstance, releaseRestoreCreatedInstance, instances,
+  waitForInitialWorkspaceLoad, waitForInstanceInitialSessionHydration,
+} from "../../stores/instances"
+import { openSidecarTab, SidecarNotFoundError } from "../../stores/sidecars"
+import {
+  hydrateRestoredWorkspaceState,
+} from "../../stores/app-session-workspace-hydration"
+import { runWithSerializedCommits } from "../../stores/app-session-restore-queue"
+import { waitForSettledPrerequisite } from "../trailing-resync"
+const log = getLogger("actions")
+const INITIAL_LOAD_TIMEOUT_MS = 15_000
+const OPERATION_TIMEOUT_MS = 30_000
+const CREATE_TIMEOUT_MS = OPERATION_TIMEOUT_MS * 2
+const CLEANUP_TIMEOUT_MS = 5_000
+const MINIMUM_STARTUP_TIMEOUT_MS = 60_000
+function startupTimeout(snapshot: RestorableSessionState): number {
+  const workspaceCount = snapshot.tabs.filter((tab) => tab.kind === "workspace").length
+  return Math.max(MINIMUM_STARTUP_TIMEOUT_MS,
+    INITIAL_LOAD_TIMEOUT_MS + Math.max(1, workspaceCount) * (CREATE_TIMEOUT_MS + CLEANUP_TIMEOUT_MS) + 5_000)
+}
+async function disposeFailedRestoreWorkspace(instanceId: string): Promise<void> {
+  const cleanup = disposeRestoreCreatedInstance(instanceId)
+  try {
+    await runAbortable(() => cleanup, {
+      timeoutMs: CLEANUP_TIMEOUT_MS,
+      message: `Timed out cleaning up restored workspace ${instanceId}`,
+    })
+  } catch (error) {
+    log.warn("Restore workspace cleanup continues in the background", { instanceId, error })
+  }
+}
+function createRestoreContext(snapshot: RestorableSessionState, signal: AbortSignal, capture: AppSessionCaptureController) {
+  const orderRevision = appTabOrderRevision()
+  const selectionRevision = appTabSelectionRevision()
+  let ownedActiveTabId: string | null = null
+  return {
+    snapshot, signal, capture,
+    selectActive(tabId: string | null, requested: boolean) {
+      if (appTabSelectionRevision() !== selectionRevision) return
+      const current = activeAppTabId()
+      if ((current && current !== ownedActiveTabId) || (!requested && ownedActiveTabId)) return
+      selectAppTab(tabId, { source: "restore" })
+      ownedActiveTabId = tabId
+    },
+    applyOrder() {
+      if (appTabOrderRevision() === orderRevision) {
+        setAppTabOrder(capture.restoredTabIds().filter((id): id is string => Boolean(id)))
+      }
+    },
+  }
+}
+type RestoreContext = ReturnType<typeof createRestoreContext>
+const waitForWorkspaceMountAdoption = () => new Promise<void>((resolve) => setTimeout(resolve, 0))
+async function restoreTabs(context: RestoreContext): Promise<void> {
+  const { snapshot, signal, capture } = context
+  const sidecars = snapshot.tabs.map((tab, index) => tab.kind === "sidecar" ? restoreSidecar(tab, index) : undefined)
+  try {
+    await runAbortable(async (operationSignal) => {
+      await waitForInitialWorkspaceLoad()
+      if (operationSignal.aborted) throw getAbortReason(operationSignal)
+    }, { timeoutMs: INITIAL_LOAD_TIMEOUT_MS, message: "Timed out loading initial workspaces", signal })
+  } catch (error) {
+    log.error("Failed to load workspaces before restoring app session", error)
+    return Promise.all(sidecars).then(() => undefined)
+  }
+  if (signal.aborted) return Promise.all(sidecars).then(() => undefined)
+  const matches = reconcileWorkspaceTabs(snapshot.tabs.map((tab) => tab.kind === "workspace"
+    ? { kind: tab.kind, folderPath: tab.folder, occurrence: tab.occurrence }
+     : { kind: tab.kind }), Array.from(instances().values())
+       .map(({ id, folder, status }) => ({ id, folderPath: folder, status })))
+  const existing = matches.filter(({ existingWorkspaceId }) => existingWorkspaceId)
+  const missing = matches.filter(({ existingWorkspaceId }) => !existingWorkspaceId)
+  existing.forEach(({ tabIndex, existingWorkspaceId }) =>
+    capture.recordRestoredTab(tabIndex, getInstanceAppTabId(existingWorkspaceId!)))
+  const claimedIds = new Set(existing.map(({ existingWorkspaceId }) => existingWorkspaceId!))
+  context.applyOrder()
+  const restoredIds = capture.restoredTabIds()
+  const provisionalId = resolveRestoredActiveTabId(restoredIds, snapshot.activeTabIndex)
+  if (provisionalId) context.selectActive(provisionalId, provisionalId === restoredIds[snapshot.activeTabIndex])
+  const restoreWorkspace = async (
+    match: (typeof matches)[number],
+    waitForCreateCommit?: Promise<void>,
+    finishCreateCommit?: () => void,
+  ) => {
+    if (signal.aborted) return
+    const tab = snapshot.tabs[match.tabIndex]
+    if (!tab || tab.kind !== "workspace") return
+    let createdId: string | null = null
+    const canCommitCreation = capture.createRestoredTabCommitGuard(match.tabIndex)
+    try {
+      const instanceId = await runAbortable(async (operationSignal) => {
+        const existingId = match.existingWorkspaceId
+        const create = (forceNew: boolean) => createInstance(tab.folder, tab.binaryPath, tab.projectName, {
+          activate: false, signal: operationSignal, forceNew,
+          waitForCreateCommit: waitForCreateCommit ? () => waitForCreateCommit : undefined,
+          shouldCreateCommit: canCommitCreation,
+          onCreateCommit: (id) => capture.recordRestoredTab(match.tabIndex, getInstanceAppTabId(id)),
+        })
+        let creation = existingId || isWebHost() ? null : await create(match.descriptor.occurrence > 0)
+        if (creation && claimedIds.has(creation.instanceId)) {
+          if (operationSignal.aborted) throw getAbortReason(operationSignal)
+          if (creation.requestId) await cancelRestoreCreationRequest(creation.instanceId, creation.requestId)
+          creation = await create(true)
+        }
+        if (creation && finishCreateCommit) await waitForWorkspaceMountAdoption()
+        finishCreateCommit?.()
+        const id = existingId ?? creation?.instanceId ?? null
+        if (!id) return null
+        claimedIds.add(id)
+        const created = creation?.reused === false
+        if (created) createdId = id
+        try {
+          // A reconnect can recover the list; saved IDs still restore directly after an initial failure.
+          await runAbortable(
+            () => waitForSettledPrerequisite(waitForInstanceInitialSessionHydration(id)),
+            { signal: operationSignal },
+          )
+          const tabId = getInstanceAppTabId(id)
+          const isCurrentBinding = () => capture.hasRestoredTabBinding(match.tabIndex, tabId)
+          if (!isCurrentBinding()) return id
+          const unavailable = await hydrateRestoredWorkspaceState(id, tab, operationSignal, isCurrentBinding)
+          if (operationSignal.aborted) throw getAbortReason(operationSignal)
+          if (!unavailable || !isCurrentBinding()) return id
+          if (creation?.requestId) await releaseRestoreCreatedInstance(id, creation.requestId)
+          if (operationSignal.aborted) throw getAbortReason(operationSignal)
+          if (capture.settleRestoredTab(match.tabIndex, tabId, tabId, unavailable)
+            && match.tabIndex === snapshot.activeTabIndex) context.selectActive(tabId, true)
+        } catch (error) {
+          if (!existingId && creation?.requestId) {
+            capture.settleRestoredTab(match.tabIndex, getInstanceAppTabId(id), null)
+            if (created) createdId = null
+            await disposeFailedRestoreWorkspace(id)
+          }
+          throw error
+        }
+        return id
+      }, {
+        timeoutMs: match.existingWorkspaceId ? OPERATION_TIMEOUT_MS : CREATE_TIMEOUT_MS,
+        message: `Timed out restoring workspace ${tab.folder}`, signal,
+      })
+      if (!signal.aborted && !instanceId) {
+        log.info("Skipped automatic remote workspace launch while restoring browser state", { folder: tab.folder })
+      }
+    } catch (error) {
+      if (createdId) {
+        capture.settleRestoredTab(match.tabIndex, getInstanceAppTabId(createdId), null)
+        await disposeFailedRestoreWorkspace(createdId)
+      }
+      if (!signal.aborted) log.warn("Skipped workspace while restoring app session", { folder: tab.folder, error })
+    }
+  }
+  async function restoreSidecar(tab: Extract<RestorableSessionState["tabs"][number], { kind: "sidecar" }>,
+    index: number) {
+    if (signal.aborted) return
+    try {
+      const opened = await runAbortable((operationSignal) => openSidecarTab(tab.sidecarId, {
+        activate: false, propagateLoadErrors: true, signal: operationSignal,
+      }), { timeoutMs: OPERATION_TIMEOUT_MS, message: `Timed out restoring SideCar ${tab.sidecarId}`, signal })
+      if (signal.aborted) return
+      const tabId = getSidecarAppTabId(opened.token)
+      capture.recordRestoredTab(index, tabId, new Set())
+      if (index === snapshot.activeTabIndex) context.selectActive(tabId, true)
+    } catch (error) {
+      if (error instanceof SidecarNotFoundError) capture.recordRestoredTab(index, null, new Set())
+      if (!signal.aborted) log.warn("Skipped SideCar while restoring app session", { sidecarId: tab.sidecarId, error })
+    }
+  }
+  const restoreMissing = () => runWithSerializedCommits(
+    [...missing].sort((a, b) => a.tabIndex - b.tabIndex),
+    (match, waitForCommit, finishCommit) => restoreWorkspace(match, waitForCommit, finishCommit),
+  )
+  await Promise.all([...existing.map((match) => restoreWorkspace(match)), restoreMissing(), ...sidecars])
+}
+export function useAppSessionRestore(): void {
+  const capture = useAppSessionCapture()
+  const controller = new AbortController()
+  let disposed = false
+  onMount(() => {
+    const snapshot = loadedRestorableSession()
+    setShowFolderSelection(snapshot?.homeActive === true)
+    void (async () => {
+      try {
+        await capture.ready
+        if (!shouldRestoreSessionState(clientStateIsPrimary(), restorePreviousStateEnabled(), snapshot)) return capture.start()
+        capture.start(snapshot!)
+        await runAbortable(async (signal) => {
+          const context = createRestoreContext(snapshot!, signal, capture)
+          await restoreTabs(context)
+          if (signal.aborted) return
+          context.applyOrder()
+          if (!activeAppTabId()) {
+            context.selectActive(resolveRestoredActiveTabId(capture.restoredTabIds(), snapshot!.activeTabIndex), true)
+          }
+        }, {
+          timeoutMs: startupTimeout(snapshot!), message: "Timed out restoring the saved app session", signal: controller.signal,
+        })
+      } catch (error) {
+        log.error("Failed to restore app session", error)
+      } finally {
+        if (!disposed) releaseAppSessionRestoreGate()
+      }
+    })()
+  })
+  onCleanup(() => {
+    disposed = true
+    controller.abort(new Error("App session restore disposed"))
+    releaseAppSessionRestoreGate()
+  })
+}
diff --git a/packages/ui/src/lib/hooks/use-commands.ts b/packages/ui/src/lib/hooks/use-commands.ts
index 734ceb4e..e11c9765 100644
--- a/packages/ui/src/lib/hooks/use-commands.ts
+++ b/packages/ui/src/lib/hooks/use-commands.ts
@@ -1,6 +1,11 @@
 import { createSignal, onMount } from "solid-js"
 import type { Accessor } from "solid-js"
-import type { Preferences, ExpansionPreference, ToolInputsVisibilityPreference } from "../../stores/preferences"
+import type {
+  Preferences,
+  ExpansionPreference,
+  ToolInputsVisibilityPreference,
+  VisibilityPreference,
+} from "../../stores/preferences"
 import { createCommandRegistry, type Command } from "../commands"
 import { activeInstanceId } from "../../stores/instances"
 import { selectNextAppTab, selectPreviousAppTab } from "../../stores/app-tabs"
@@ -40,8 +45,8 @@ export interface UseCommandsOptions {
   togglePromptSubmitOnEnter: () => void
   toggleShowPromptVoiceInput: () => void
   setDiffViewMode: (mode: "split" | "unified") => void
-  setToolOutputExpansion: (mode: ExpansionPreference) => void
-  setDiagnosticsExpansion: (mode: ExpansionPreference) => void
+  setToolOutputExpansion: (mode: VisibilityPreference) => void
+  setDiagnosticsExpansion: (mode: VisibilityPreference) => void
   setThinkingBlocksExpansion: (mode: ExpansionPreference) => void
   setToolInputsVisibility: (mode: ToolInputsVisibilityPreference) => void
   handleNewInstanceRequest: () => void
diff --git a/packages/ui/src/lib/hooks/use-remote-server-profiles.ts b/packages/ui/src/lib/hooks/use-remote-server-profiles.ts
new file mode 100644
index 00000000..1fea22b1
--- /dev/null
+++ b/packages/ui/src/lib/hooks/use-remote-server-profiles.ts
@@ -0,0 +1,77 @@
+import { createSignal } from "solid-js"
+import { serverApi } from "../api-client"
+import { useI18n } from "../i18n"
+import { openRemoteServerWindow } from "../native/remote-window"
+import { canOpenRemoteWindows, isTauriHost } from "../runtime-env"
+import { showAlertDialog } from "../../stores/alerts"
+import { useConfig } from "../../stores/preferences"
+
+export type RemoteServerInput = {
+  id?: string
+  name: string
+  baseUrl: string
+  skipTlsVerify: boolean
+}
+
+export function useRemoteServerProfiles() {
+  const { t } = useI18n()
+  const { remoteServers, saveRemoteServerProfile, markRemoteServerConnected, removeRemoteServerProfile } = useConfig()
+  const [connectingServerId, setConnectingServerId] = createSignal<string | null>(null)
+
+  const saveServer = async (input: RemoteServerInput, openWindow: boolean) => {
+    if (openWindow && !canOpenRemoteWindows()) {
+      throw new Error("Remote server windows can only be opened from a local desktop window")
+    }
+
+    const name = input.name.trim()
+    const baseUrl = input.baseUrl.trim()
+    if (!name || !baseUrl) throw new Error(t("folderSelection.servers.dialog.errorRequired"))
+
+    const probe = await serverApi.probeRemoteServer({ baseUrl, skipTlsVerify: input.skipTlsVerify })
+    if (!probe.ok) throw new Error(probe.error || t("folderSelection.servers.dialog.errorConnect"))
+
+    const profile = await saveRemoteServerProfile({
+      id: input.id,
+      name,
+      baseUrl: probe.normalizedUrl,
+      skipTlsVerify: input.skipTlsVerify,
+    })
+
+    if (openWindow) {
+      const proxySession =
+        isTauriHost() && profile.skipTlsVerify && profile.baseUrl.startsWith("https://")
+          ? await serverApi.createRemoteProxySession({ baseUrl: profile.baseUrl, skipTlsVerify: true })
+          : undefined
+
+      try {
+        await openRemoteServerWindow(profile, proxySession?.windowUrl, proxySession?.sessionId)
+      } catch (error) {
+        if (proxySession) void serverApi.deleteRemoteProxySession(proxySession.sessionId).catch(() => {})
+        throw error
+      }
+      await markRemoteServerConnected(profile.id)
+    }
+
+    return profile
+  }
+
+  const connectSavedServer = async (id: string) => {
+    if (!canOpenRemoteWindows() || connectingServerId()) return
+    const target = remoteServers().find((server) => server.id === id)
+    if (!target) return
+
+    setConnectingServerId(id)
+    try {
+      await saveServer(target, true)
+    } catch (error) {
+      showAlertDialog(error instanceof Error ? error.message : String(error), {
+        title: t("folderSelection.servers.errorTitle"),
+        variant: "warning",
+      })
+    } finally {
+      setConnectingServerId(null)
+    }
+  }
+
+  return { remoteServers, connectingServerId, saveServer, connectSavedServer, removeRemoteServerProfile }
+}
diff --git a/packages/ui/src/lib/hooks/use-speech.ts b/packages/ui/src/lib/hooks/use-speech.ts
index 41bf0cee..45432caf 100644
--- a/packages/ui/src/lib/hooks/use-speech.ts
+++ b/packages/ui/src/lib/hooks/use-speech.ts
@@ -105,7 +105,7 @@ export function useSpeech(options: UseSpeechOptions) {
 
   const canUseSpeech = () => {
     const capabilities = speechCapabilities()
-    if (!isSupported() || !capabilities?.available || !capabilities?.configured || !capabilities?.supportsTts) {
+    if (!isSupported() || !capabilities?.available || !capabilities?.ttsConfigured || !capabilities?.supportsTts) {
       return false
     }
     return getSpeechPlaybackSupport({
@@ -136,7 +136,7 @@ export function useSpeech(options: UseSpeechOptions) {
     }
 
     const capabilities = (await loadSpeechCapabilities()) ?? speechCapabilities()
-    if (!capabilities?.available || !capabilities?.configured || !capabilities?.supportsTts) {
+    if (!capabilities?.available || !capabilities?.ttsConfigured || !capabilities?.supportsTts) {
       showAlertDialog(t("messageItem.actions.speak.error.unavailable"), {
         title: t("messageItem.actions.speak.error.title"),
         variant: "error",
diff --git a/packages/ui/src/lib/hooks/use-transcription-test.ts b/packages/ui/src/lib/hooks/use-transcription-test.ts
new file mode 100644
index 00000000..a30710aa
--- /dev/null
+++ b/packages/ui/src/lib/hooks/use-transcription-test.ts
@@ -0,0 +1,185 @@
+import { createSignal, onCleanup } from "solid-js"
+import { showAlertDialog } from "../../stores/alerts"
+import { speechCapabilities } from "../../stores/speech"
+import { serverApi } from "../api-client"
+import { useI18n } from "../i18n"
+import { isElectronHost } from "../runtime-env"
+import { blobToBase64, createMediaRecorder, stopTracks } from "../audio-utils"
+
+type TranscriptionTestState = "idle" | "requesting" | "recording" | "transcribing"
+
+export function useTranscriptionTest() {
+  const { t } = useI18n()
+  const [state, setState] = createSignal<TranscriptionTestState>("idle")
+  const [result, setResult] = createSignal<string | null>(null)
+
+  let mediaRecorder: MediaRecorder | null = null
+  let mediaStream: MediaStream | null = null
+  let recordedChunks: Blob[] = []
+  let requestGeneration = 0
+  let disposed = false
+
+  const isSupported = () => {
+    if (typeof window === "undefined") return false
+    return typeof window.MediaRecorder !== "undefined" && Boolean(navigator.mediaDevices?.getUserMedia)
+  }
+
+  const canUseTranscription = () => {
+    const capabilities = speechCapabilities()
+    return Boolean(isSupported() && capabilities?.available && capabilities?.sttConfigured && capabilities?.supportsStt)
+  }
+
+  const releaseStream = () => {
+    stopTracks(mediaStream)
+    mediaStream = null
+  }
+
+  const releaseAll = () => {
+    if (mediaRecorder && mediaRecorder.state !== "inactive") {
+      mediaRecorder.stop()
+    }
+    mediaRecorder = null
+    releaseStream()
+    recordedChunks = []
+  }
+
+  onCleanup(() => {
+    disposed = true
+    requestGeneration += 1
+    releaseAll()
+  })
+
+  const startRecording = async () => {
+    if (!isSupported()) {
+      showAlertDialog(t("promptInput.voiceInput.error.unsupported"), {
+        title: t("promptInput.voiceInput.error.title"),
+        variant: "error",
+      })
+      return
+    }
+
+    const generation = ++requestGeneration
+    setState("requesting")
+    setResult(null)
+
+    try {
+      if (isElectronHost()) {
+        const granted = await (window as Window & { electronAPI?: ElectronAPI }).electronAPI?.requestMicrophoneAccess?.()
+        if (granted && !granted.granted) {
+          throw new Error(t("promptInput.voiceInput.error.permissionDenied"))
+        }
+      }
+
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
+
+      if (generation !== requestGeneration || disposed) {
+        stopTracks(stream)
+        return
+      }
+
+      recordedChunks = []
+      mediaStream = stream
+      const recorder = createMediaRecorder(stream)
+      mediaRecorder = recorder
+
+      recorder.addEventListener("dataavailable", (event) => {
+        if (event.data.size > 0 && generation === requestGeneration) {
+          recordedChunks.push(event.data)
+        }
+      })
+
+      recorder.addEventListener("error", () => {
+        if (generation !== requestGeneration) return
+        releaseAll()
+        setState("idle")
+      })
+
+      recorder.addEventListener("stop", () => {
+        if (generation === requestGeneration) {
+          void finalizeRecording(generation)
+        }
+      })
+
+      setState("recording")
+      recorder.start()
+    } catch (error) {
+      if (generation !== requestGeneration) return
+      releaseAll()
+      setState("idle")
+      showAlertDialog(t("promptInput.voiceInput.error.permission"), {
+        title: t("promptInput.voiceInput.error.title"),
+        detail: error instanceof Error ? error.message : String(error),
+        variant: "error",
+      })
+    }
+  }
+
+  const stopRecording = () => {
+    if (!mediaRecorder || state() !== "recording") return
+    mediaRecorder.stop()
+    releaseStream()
+    setState("transcribing")
+  }
+
+  const finalizeRecording = async (generation: number) => {
+    const chunks = recordedChunks
+    recordedChunks = []
+    const recorder = mediaRecorder
+    mediaRecorder = null
+
+    if (generation !== requestGeneration || chunks.length === 0) {
+      if (generation === requestGeneration) setState("idle")
+      return
+    }
+
+    const mimeType = recorder?.mimeType || chunks[0]?.type || "audio/webm"
+
+    try {
+      const audioBlob = new Blob(chunks, { type: mimeType })
+      const transcription = await serverApi.transcribeAudio({
+        audioBase64: await blobToBase64(audioBlob),
+        mimeType,
+      })
+      if (generation === requestGeneration) {
+        setResult(transcription.text.trim() || t("settings.speech.testInput.empty"))
+      }
+    } catch (error) {
+      if (generation === requestGeneration) {
+        showAlertDialog(t("promptInput.voiceInput.error.transcribe"), {
+          title: t("promptInput.voiceInput.error.title"),
+          detail: error instanceof Error ? error.message : String(error),
+          variant: "error",
+        })
+      }
+    } finally {
+      if (generation === requestGeneration) {
+        setState("idle")
+      }
+    }
+  }
+
+  const toggle = async () => {
+    if (state() === "recording") {
+      stopRecording()
+      return
+    }
+    if (state() === "idle") {
+      await startRecording()
+    }
+  }
+
+  return {
+    state,
+    result,
+    canUseTranscription,
+    isRecording: () => state() === "recording",
+    isTranscribing: () => state() === "transcribing",
+    toggle,
+    buttonTitle: () => {
+      if (state() === "requesting") return t("settings.speech.testInput.requesting")
+      if (state() === "recording") return t("settings.speech.testInput.stop")
+      if (state() === "transcribing") return t("settings.speech.testInput.transcribing")
+      return t("settings.speech.testInput.action")
+    },
+  }
+}
diff --git a/packages/ui/src/lib/i18n/messages/de/commands.ts b/packages/ui/src/lib/i18n/messages/de/commands.ts
index 8480b648..5962a1aa 100644
--- a/packages/ui/src/lib/i18n/messages/de/commands.ts
+++ b/packages/ui/src/lib/i18n/messages/de/commands.ts
@@ -123,12 +123,12 @@ export const commandMessages = {
   "commands.diffViewUnified.keywords": "diff, einheitlich, ansicht",
 
   "commands.toolOutputsDefault.label": "Standard für Tool-Ausgaben · {state}",
-  "commands.toolOutputsDefault.description": "Standardmäßige Erweiterung für Tool-Ausgaben umschalten",
-  "commands.toolOutputsDefault.keywords": "tool, ausgabe, erweitern, einklappen",
+  "commands.toolOutputsDefault.description": "Standardsichtbarkeit für Tool-Ausgaben festlegen",
+  "commands.toolOutputsDefault.keywords": "tool, ausgabe, ausblenden, erweitern, einklappen",
 
   "commands.diagnosticsDefault.label": "Standard für Diagnose · {state}",
-  "commands.diagnosticsDefault.description": "Standardmäßige Erweiterung für die Diagnoseausgabe umschalten",
-  "commands.diagnosticsDefault.keywords": "diagnose, erweitern, einklappen",
+  "commands.diagnosticsDefault.description": "Standardsichtbarkeit für Diagnoseausgaben festlegen",
+  "commands.diagnosticsDefault.keywords": "diagnose, ausblenden, erweitern, einklappen",
 
   "commands.toolInputsVisibility.label": "Sichtbarkeit von Tool-Eingaben · {state}",
   "commands.toolInputsVisibility.description": "Standardsichtbarkeit für Argumente von Tool-Aufrufen festlegen",
diff --git a/packages/ui/src/lib/i18n/messages/de/folderSelection.ts b/packages/ui/src/lib/i18n/messages/de/folderSelection.ts
index 55d99264..ac1d1807 100644
--- a/packages/ui/src/lib/i18n/messages/de/folderSelection.ts
+++ b/packages/ui/src/lib/i18n/messages/de/folderSelection.ts
@@ -17,10 +17,8 @@ export const folderSelectionMessages = {
   "folderSelection.recent.rename": "Arbeitsbereich umbenennen",
   "folderSelection.recent.remove": "Aus Liste entfernen",
   "folderSelection.recent.openBadge": "Offen",
-  "folderSelection.recent.alreadyOpenTitle": "Projekt bereits offen",
-  "folderSelection.recent.alreadyOpenMessage": "Wählen Sie, wie dieser Ordner geöffnet werden soll.",
+  "folderSelection.recent.openNewInstance": "Neue Instanz öffnen",
   "folderSelection.recent.switchToOpenProject": "Zum offenen Projekt wechseln",
-  "folderSelection.recent.openAnotherInstance": "Weitere Instanz öffnen",
 
   "folderSelection.browse.title": "Nach Ordner suchen",
   "folderSelection.browse.subtitle": "Wählen Sie einen beliebigen Ordner auf Ihrem Computer aus",
diff --git a/packages/ui/src/lib/i18n/messages/de/instance.ts b/packages/ui/src/lib/i18n/messages/de/instance.ts
index 49b64847..5b5e9018 100644
--- a/packages/ui/src/lib/i18n/messages/de/instance.ts
+++ b/packages/ui/src/lib/i18n/messages/de/instance.ts
@@ -93,6 +93,19 @@ export const instanceMessages = {
   "instanceShell.rightPanel.tabs.files": "Dateien",
   "instanceShell.rightPanel.tabs.status": "Status",
   "instanceShell.rightPanel.tabs.ariaLabel": "Tabs im rechten Panel",
+  "instanceShell.rightPanel.customize.toggle": "Rechtes Panel anpassen",
+  "instanceShell.rightPanel.customize.title": "Rechtes Panel anpassen",
+  "instanceShell.rightPanel.customize.description": "Tabs und Statusabschnitte anzeigen oder ausblenden.",
+  "instanceShell.rightPanel.customize.reset": "Zurücksetzen",
+  "instanceShell.rightPanel.customize.tabs": "Tabs",
+  "instanceShell.rightPanel.customize.statusSections": "Statusabschnitte",
+  "instanceShell.rightPanel.customize.dragToReorder": "Tabs oder Statusabschnitte ziehen, um sie neu anzuordnen.",
+  "instanceShell.rightPanel.customize.moveUp": "Nach oben",
+  "instanceShell.rightPanel.customize.moveDown": "Nach unten",
+  "instanceShell.rightPanel.customize.moveTabUp": "Tab {label} nach oben verschieben",
+  "instanceShell.rightPanel.customize.moveTabDown": "Tab {label} nach unten verschieben",
+  "instanceShell.rightPanel.customize.moveStatusSectionUp": "Statusabschnitt {label} nach oben verschieben",
+  "instanceShell.rightPanel.customize.moveStatusSectionDown": "Statusabschnitt {label} nach unten verschieben",
   "instanceShell.rightPanel.actions.refresh": "Aktualisieren",
   "instanceShell.rightPanel.actions.save": "Speichern (Ctrl+S)",
   "instanceShell.rightPanel.actions.saveConfirm.message": "Möchten Sie die Änderungen an \"{path}\" speichern, bevor Sie wechseln?",
@@ -191,8 +204,8 @@ export const instanceMessages = {
 
   "instanceShell.yoloMode.noSessionSelected": "Wählen Sie eine Sitzung aus, um den Yolo-Modus zu konfigurieren.",
   "instanceShell.yoloMode.title": "Yolo-Modus",
-  "instanceShell.yoloMode.description": "Berechtigungsanfragen für diese Sitzung automatisch genehmigen. Standardmäßig deaktiviert.",
-  "instanceShell.yoloMode.badge": "Yolo-Modus",
+  "instanceShell.yoloMode.description": "Berechtigungsanfragen für diese Sitzung automatisch genehmigen.",
+  "instanceShell.yoloMode.badge": "Yolo",
   "instanceShell.yoloMode.badgeAriaLabel": "Yolo-Modus aktiviert",
 
   "instanceShell.backgroundProcesses.empty": "Keine Hintergrundprozesse.",
diff --git a/packages/ui/src/lib/i18n/messages/de/markdown.ts b/packages/ui/src/lib/i18n/messages/de/markdown.ts
index 83d1e7fc..a37d7792 100644
--- a/packages/ui/src/lib/i18n/messages/de/markdown.ts
+++ b/packages/ui/src/lib/i18n/messages/de/markdown.ts
@@ -2,6 +2,8 @@ export const markdownMessages = {
   "markdown.codeBlock.copy.label": "Kopieren",
   "markdown.codeBlock.copy.copied": "Kopiert!",
   "markdown.codeBlock.copy.failed": "Fehlgeschlagen",
+  "markdown.codeBlock.wrap.enable": "Zeilenumbruch aktivieren",
+  "markdown.codeBlock.wrap.disable": "Zeilenumbruch deaktivieren",
 
   "markdown.copy": "Kopieren",
 } as const
diff --git a/packages/ui/src/lib/i18n/messages/de/messaging.ts b/packages/ui/src/lib/i18n/messages/de/messaging.ts
index da8a4e95..238db557 100644
--- a/packages/ui/src/lib/i18n/messages/de/messaging.ts
+++ b/packages/ui/src/lib/i18n/messages/de/messaging.ts
@@ -17,6 +17,7 @@ export const messagingMessages = {
   "messageSection.empty.tips.attachFilesPrefix": "Dateien anhängen mit",
   "messageSection.loading.messages": "Nachrichten werden geladen...",
   "messageSection.loadError.title": "Nachrichten konnten nicht geladen werden",
+  "messageSection.loadError.detail": "OpenCode hat die Sitzungsnachrichten nicht zurückgegeben.",
   "messageSection.loadError.reload": "Nachrichten neu laden",
   "messageSection.scroll.toFirstAriaLabel": "Zur ersten Nachricht scrollen",
   "messageSection.scroll.toLatestAriaLabel": "Zur neuesten Nachricht scrollen",
@@ -71,6 +72,8 @@ export const messagingMessages = {
   "messageBlock.usage.cacheRead": "Cache-Lesen",
   "messageBlock.usage.cacheWrite": "Cache-Schreiben",
   "messageBlock.usage.cost": "Kosten",
+  "messageBlock.usage.expandAriaLabel": "Token-Metriken erweitern",
+  "messageBlock.usage.collapseAriaLabel": "Token-Metriken einklappen",
   "messageBlock.step.agentLabel": "Agent: {agent}",
   "messageBlock.step.modelLabel": "Modell: {model}",
   "messageBlock.reasoning.thinkingLabel": "Denken",
diff --git a/packages/ui/src/lib/i18n/messages/de/session.ts b/packages/ui/src/lib/i18n/messages/de/session.ts
index ddf29af3..1f35a570 100644
--- a/packages/ui/src/lib/i18n/messages/de/session.ts
+++ b/packages/ui/src/lib/i18n/messages/de/session.ts
@@ -15,6 +15,7 @@ export const sessionMessages = {
   "sessionList.status.working": "Arbeitet",
   "sessionList.status.compacting": "Wird komprimiert",
   "sessionList.status.idle": "Bereit",
+  "sessionList.status.interrupted": "Unterbrochen",
   "sessionList.status.retrying": "Wiederholung",
   "sessionList.status.retryingIn": "Wiederholung in {seconds}s",
   "sessionList.status.retryTooltip": "{message} (Versuch {attempt})",
@@ -48,6 +49,10 @@ export const sessionMessages = {
   "sessionList.filter.placeholder": "Sitzungen suchen...",
   "sessionList.filter.ariaLabel": "Sitzungen suchen",
   "sessionList.loading.more": "Weitere Sitzungen werden geladen...",
+  "sessionList.loading.initial": "Sitzungen werden geladen...",
+  "sessionList.loadError.title": "Sitzungen konnten nicht geladen werden",
+  "sessionList.loadError.detail": "OpenCode hat keine Sitzungsliste zurückgegeben.",
+  "sessionList.loadError.retry": "Erneut versuchen",
   "sessionList.selection.selectAllLabel": "Alle auswählen",
   "sessionList.selection.selectAllAriaLabel": "Alle Sitzungen auswählen",
   "sessionList.selection.clearLabel": "Leeren",
diff --git a/packages/ui/src/lib/i18n/messages/de/settings.ts b/packages/ui/src/lib/i18n/messages/de/settings.ts
index e247fe3d..49794fa8 100644
--- a/packages/ui/src/lib/i18n/messages/de/settings.ts
+++ b/packages/ui/src/lib/i18n/messages/de/settings.ts
@@ -56,6 +56,7 @@ export const settingsMessages = {
   "contextUsagePanel.labels.input": "Eingabe",
   "contextUsagePanel.labels.output": "Ausgabe",
   "contextUsagePanel.labels.cost": "Kosten",
+  "contextUsagePanel.included": "Inbegriffen",
   "contextUsagePanel.labels.totalInput": "Gesamt Ein",
   "contextUsagePanel.labels.totalOutput": "Gesamt Aus",
   "contextUsagePanel.labels.totalCost": "Gesamtkosten",
@@ -64,6 +65,32 @@ export const settingsMessages = {
   "contextUsagePanel.labels.available": "Verfügbar",
   "contextUsagePanel.unavailable": "--",
 
+  "providerUsage.title": "Nutzung",
+  "providerUsage.tooltip": "Nutzung und Rücksetzungszeiträume des in der aktiven Sitzung ausgewählten Anbieters.",
+  "providerUsage.noSession": "Wählen Sie eine Sitzung aus, um die Tarifnutzung anzuzeigen.",
+  "providerUsage.loading": "Nutzung wird geladen...",
+  "providerUsage.unsupported": "Für diesen Anbieter sind keine Nutzungsdaten verfügbar.",
+  "providerUsage.notConfigured": "Keine kompatiblen Abonnement-Zugangsdaten gefunden.",
+  "providerUsage.unavailable": "Nutzungsdaten sind vorübergehend nicht verfügbar.",
+  "providerUsage.unavailableValue": "--",
+  "providerUsage.usedPercent": "{percent} % verwendet",
+  "providerUsage.resets": "Zurücksetzung {time}",
+  "providerUsage.progressLabel": "Tarifnutzung {window}",
+  "providerUsage.windows.fiveHours": "5 Stunden",
+  "providerUsage.windows.sevenDays": "7 Tage",
+  "providerUsage.windows.sevenDaysSonnet": "7 Tage · Sonnet",
+  "providerUsage.windows.sevenDaysOpus": "7 Tage · Opus",
+  "providerUsage.windows.weekly": "Wöchentlich",
+  "providerUsage.windows.daily": "Täglich",
+  "providerUsage.windows.monthly": "Monatlich",
+  "providerUsage.windows.credits": "Guthaben",
+  "providerUsage.windows.billingCycle": "Abrechnungszeitraum",
+  "providerUsage.windows.session": "Sitzung",
+  "providerUsage.windows.premium": "Premium-Anfragen",
+  "providerUsage.windows.chat": "Chat",
+  "providerUsage.windows.completions": "Vervollständigungen",
+  "providerUsage.windows.mcpTools": "MCP-Werkzeuge",
+
   "settings.title": "Einstellungen",
   "settings.navigationAriaLabel": "Einstellungsbereiche",
   "settings.close": "Einstellungen schließen",
@@ -71,6 +98,16 @@ export const settingsMessages = {
   "settings.open.title": "Einstellungen öffnen",
   "settings.open.ariaLabel": "Einstellungen öffnen",
   "settings.nav.appearance": "Aussehen",
+  "settings.nav.general": "Allgemein",
+  "settings.nav.chat": "Chat",
+  "settings.nav.voice": "Sprache",
+  "settings.nav.connections": "Verbindungen",
+  "settings.nav.runtime": "Laufzeit",
+  "settings.nav.advanced": "Erweitert",
+  "settings.nav.about": "Über",
+  "settings.general.language.subtitle": "Wähle die Sprache für die gesamte Anwendung.",
+  "settings.behavior.holdLongAssistantReplies.title": "Lange Assistentenantworten anhalten",
+  "settings.behavior.holdLongAssistantReplies.subtitle": "Automatisches Folgen beenden, wenn eine laufende Antwort über das Ansichtsfenster hinausgeht.",
   "settings.nav.notifications": "Benachrichtigungen",
   "settings.nav.remote": "Remote-Zugriff",
   "settings.nav.speech": "Sprache",
@@ -89,6 +126,16 @@ export const settingsMessages = {
   "settings.appearance.theme.option.system": "An Betriebssystem-Einstellung anpassen",
   "settings.appearance.theme.option.light": "Helles Design verwenden",
   "settings.appearance.theme.option.dark": "Dunkles Design verwenden",
+  "settings.appearance.startup.title": "Startverhalten",
+  "settings.appearance.startup.subtitle": "Lege fest, was dieses Gerät beim Start von CodeNomad wiederherstellt.",
+  "settings.appearance.startup.restore.title": "Vorherigen Zustand wiederherstellen",
+  "settings.appearance.startup.restore.subtitle": "Arbeitsbereichs- und Sidecar-Tabs, aktive Sitzungen und nicht gesendete Nachrichten erneut öffnen sowie Scrollpositionen, Panel-Layout, Fensterposition und Zoom wiederherstellen.",
+  "settings.appearance.startup.clear.title": "Gespeicherter Startzustand",
+  "settings.appearance.startup.clear.subtitle": "Gespeicherte Tabs, Entwürfe, Scrollpositionen und das Panel-Layout entfernen. CodeNomad- und OpenCode-Daten werden nicht gelöscht.",
+  "settings.appearance.startup.clear.action": "Gespeicherten Zustand löschen",
+  "settings.appearance.startup.clearSuccess": "Gespeicherter Startzustand wurde gelöscht.",
+  "settings.appearance.startup.clearError": "Der gespeicherte Startzustand konnte nicht gelöscht werden.",
+  "settings.appearance.startup.updateError": "Die Einstellung zur Wiederherstellung beim Start konnte nicht aktualisiert werden.",
   "settings.section.notifications.title": "Benachrichtigungen",
   "settings.section.notifications.subtitle": "Steuern Sie OS-Benachrichtigungen für Sitzungsaktivitäten.",
   "settings.notifications.permission.granted": "Erteilt",
@@ -132,6 +179,18 @@ export const settingsMessages = {
   "settings.opencode.logLevel.option.info": "Info",
   "settings.opencode.logLevel.option.warn": "Warn",
   "settings.opencode.logLevel.option.error": "Fehler",
+  "settings.opencode.update.title": "OpenCode-Updates",
+  "settings.opencode.update.subtitle": "Updates für die konfigurierte OpenCode-Binärdatei prüfen und installieren.",
+  "settings.opencode.update.checking": "Updates werden gesucht...",
+  "settings.opencode.update.checkFailed": "OpenCode-Updates konnten nicht geprüft werden.",
+  "settings.opencode.update.retry": "Erneut versuchen",
+  "settings.opencode.update.installed": "Installierte Version",
+  "settings.opencode.update.upToDate": "OpenCode ist aktuell.",
+  "settings.opencode.update.action": "Auf OpenCode {version} aktualisieren",
+  "settings.opencode.update.updating": "OpenCode wird aktualisiert...",
+  "settings.opencode.update.requiresInstance": "Starten Sie einen Arbeitsbereich mit dieser Binärdatei, um das Update zu installieren.",
+  "settings.opencode.update.success": "OpenCode {version} ist installiert. Neue Instanzen verwenden die aktualisierte Version.",
+  "settings.opencode.update.failed": "Das OpenCode-Update ist fehlgeschlagen. Die installierte Version wurde nicht geändert.",
   "settings.configFiles.title": "Konfigurationsdateien",
   "settings.configFiles.subtitle": "Bearbeiten Sie freigegebene globale Konfigurationsdateien auf diesem Server.",
   "settings.configFiles.selector.label": "Datei",
@@ -151,6 +210,7 @@ export const settingsMessages = {
   "settings.configFiles.confirmDiscard.cancelLabel": "Weiter bearbeiten",
 
   "settings.providers.title": "Anbieter-Authentifizierung",
+  "settings.providers.target": "OpenCode-Instanz: {workspace}",
   "settings.providers.subtitle": "API-Schlüssel oder OAuth-Konten für die aktive OpenCode-Instanz verbinden.",
   "settings.providers.refresh": "Aktualisieren",
   "settings.providers.selectProvider": "Anbieter auswählen",
@@ -209,8 +269,8 @@ export const settingsMessages = {
 
 
   "settings.appearance.behavior.title": "Interaktion",
-  "settings.appearance.behavior.subtitle": "Standardwerte für Nachrichten, Diffs und Eingaben.",
-  "settings.behavior.expansionPresets.ariaLabel": "Transcript detail presets",
+  "settings.appearance.behavior.subtitle": "Steuere Details fuer Nachrichten, Tools, Diagnosen und Nutzung gemeinsam.",
+  "settings.behavior.expansionPresets.ariaLabel": "Voreinstellungen fuer Gespraechsdetails",
   "settings.behavior.expansionPreset.minimal.title": "Minimal",
   "settings.behavior.expansionPreset.minimal.description": "Keep most generated detail tucked away until needed.",
   "settings.behavior.expansionPreset.balanced.title": "Balanced",
@@ -267,6 +327,7 @@ export const settingsMessages = {
   "settings.speech.status.loading": "Konfiguration wird geprüft...",
   "settings.speech.status.configured": "Konfiguriert",
   "settings.speech.status.missing": "API-Schlüssel fehlt",
+  "settings.speech.status.partial": "Teilweise konfiguriert",
   "settings.speech.status.error": "Sprachdienst nicht verfügbar",
   "settings.speech.apiKey.title": "API-Schlüssel",
   "settings.speech.apiKey.subtitle": "Wird für CodeNomad-gesteuerte Sprachanfragen verwendet.",
@@ -298,11 +359,44 @@ export const settingsMessages = {
   "settings.speech.testPlayback.stop": "Beispiel stoppen",
   "settings.speech.testPlayback.sample": "Vielen Dank für die Nutzung von CodeNomad. Ihre Spracheinstellungen funktionieren einwandfrei.",
   "settings.speech.testPlayback.note": "Der Test verwendet sofort den aktuellen Modus und das Format.",
+  "settings.speech.testInput.action": "Eingabe testen",
+  "settings.speech.testInput.stop": "Aufnahme stoppen",
+  "settings.speech.testInput.transcribing": "Transkribierung",
+  "settings.speech.testInput.requesting": "Starten…",
+  "settings.speech.testInput.empty": "Keine Sprache erkannt",
   "settings.speech.save.action": "Speichern",
   "settings.speech.save.saving": "Wird gespeichert...",
   "settings.speech.save.saved": "Gespeichert",
   "settings.speech.save.unsaved": "Ungespeicherte Änderungen",
   "settings.speech.save.error": "Speichern fehlgeschlagen",
+  "settings.speech.separateProviders.title": "Getrennte Anbieter für Ein- und Ausgabe",
+  "settings.speech.separateProviders.subtitle": "Unterschiedliche API-Schlüssel und Endpunkte für Spracheingabe (STT) und Ausgabe (TTS) verwenden.",
+  "settings.speech.stt.section.title": "Spracheingabe (Sprache zu Text)",
+  "settings.speech.tts.section.title": "Sprachausgabe (Text zu Sprache)",
+  "settings.speech.stt.apiKey.title": "Eingabe-API-Schlüssel",
+  "settings.speech.stt.apiKey.subtitle": "Wird für Sprache-zu-Text-Anfragen verwendet.",
+  "settings.speech.stt.apiKey.placeholder": "Neuen Eingabe-API-Schlüssel eingeben",
+  "settings.speech.stt.apiKey.storedNote": "Ein gespeicherter Eingabe-API-Schlüssel ist ausgeblendet. Geben Sie einen neuen Wert ein, um ihn zu ersetzen.",
+  "settings.speech.stt.apiKey.usingShared": "Verwendet den gemeinsamen API-Schlüssel. Neuen Schlüssel eingeben zum Überschreiben.",
+  "settings.speech.stt.apiKey.clearAction": "Gespeicherten Eingabe-Schlüssel löschen",
+  "settings.speech.stt.apiKey.clearPending": "Der gespeicherte Eingabe-API-Schlüssel wird beim Speichern entfernt.",
+  "settings.speech.stt.baseUrl.title": "Eingabe-Basis-URL",
+  "settings.speech.stt.baseUrl.subtitle": "OpenAI-kompatibler Endpunkt für Transkription.",
+  "settings.speech.stt.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.stt.model.title": "Eingabemodell",
+  "settings.speech.stt.model.subtitle": "Modell für Sprache-zu-Text.",
+  "settings.speech.tts.apiKey.title": "Ausgabe-API-Schlüssel",
+  "settings.speech.tts.apiKey.subtitle": "Wird für Text-zu-Sprache-Anfragen verwendet.",
+  "settings.speech.tts.apiKey.placeholder": "Neuen Ausgabe-API-Schlüssel eingeben",
+  "settings.speech.tts.apiKey.storedNote": "Ein gespeicherter Ausgabe-API-Schlüssel ist ausgeblendet. Geben Sie einen neuen Wert ein, um ihn zu ersetzen.",
+  "settings.speech.tts.apiKey.usingShared": "Verwendet den gemeinsamen API-Schlüssel. Neuen Schlüssel eingeben zum Überschreiben.",
+  "settings.speech.tts.apiKey.clearAction": "Gespeicherten Ausgabe-Schlüssel löschen",
+  "settings.speech.tts.apiKey.clearPending": "Der gespeicherte Ausgabe-API-Schlüssel wird beim Speichern entfernt.",
+  "settings.speech.tts.baseUrl.title": "Ausgabe-Basis-URL",
+  "settings.speech.tts.baseUrl.subtitle": "OpenAI-kompatibler Endpunkt für Synthese.",
+  "settings.speech.tts.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.tts.model.title": "Ausgabemodell",
+  "settings.speech.tts.model.subtitle": "Modell für Text-zu-Sprache.",
   "settings.nav.sidecars": "SideCars",
   "settings.section.sidecars.eyebrow": "Server-Dienste",
   "settings.section.sidecars.title": "SideCars",
diff --git a/packages/ui/src/lib/i18n/messages/en/commands.ts b/packages/ui/src/lib/i18n/messages/en/commands.ts
index a61bddd2..3dabac04 100644
--- a/packages/ui/src/lib/i18n/messages/en/commands.ts
+++ b/packages/ui/src/lib/i18n/messages/en/commands.ts
@@ -123,12 +123,12 @@ export const commandMessages = {
   "commands.diffViewUnified.keywords": "diff, unified, view",
 
   "commands.toolOutputsDefault.label": "Tool Outputs Default · {state}",
-  "commands.toolOutputsDefault.description": "Toggle default expansion for tool outputs",
-  "commands.toolOutputsDefault.keywords": "tool, output, expand, collapse",
+  "commands.toolOutputsDefault.description": "Set default visibility for tool outputs",
+  "commands.toolOutputsDefault.keywords": "tool, output, hide, expand, collapse",
 
   "commands.diagnosticsDefault.label": "Diagnostics Default · {state}",
-  "commands.diagnosticsDefault.description": "Toggle default expansion for diagnostics output",
-  "commands.diagnosticsDefault.keywords": "diagnostics, expand, collapse",
+  "commands.diagnosticsDefault.description": "Set default visibility for diagnostics output",
+  "commands.diagnosticsDefault.keywords": "diagnostics, hide, expand, collapse",
 
   "commands.toolInputsVisibility.label": "Tool Inputs Visibility · {state}",
   "commands.toolInputsVisibility.description": "Set default visibility for tool call input arguments",
diff --git a/packages/ui/src/lib/i18n/messages/en/folderSelection.ts b/packages/ui/src/lib/i18n/messages/en/folderSelection.ts
index 9ff39771..282d2b25 100644
--- a/packages/ui/src/lib/i18n/messages/en/folderSelection.ts
+++ b/packages/ui/src/lib/i18n/messages/en/folderSelection.ts
@@ -17,10 +17,8 @@ export const folderSelectionMessages = {
   "folderSelection.recent.rename": "Rename workspace",
   "folderSelection.recent.remove": "Remove from recent",
   "folderSelection.recent.openBadge": "Open",
-  "folderSelection.recent.alreadyOpenTitle": "Project already open",
-  "folderSelection.recent.alreadyOpenMessage": "Choose how to open this folder.",
+  "folderSelection.recent.openNewInstance": "Open new instance",
   "folderSelection.recent.switchToOpenProject": "Switch to open project",
-  "folderSelection.recent.openAnotherInstance": "Open another instance",
 
   "folderSelection.browse.title": "Browse for Folder",
   "folderSelection.browse.subtitle": "Select any folder on your computer",
diff --git a/packages/ui/src/lib/i18n/messages/en/instance.ts b/packages/ui/src/lib/i18n/messages/en/instance.ts
index efcff08e..f3371780 100644
--- a/packages/ui/src/lib/i18n/messages/en/instance.ts
+++ b/packages/ui/src/lib/i18n/messages/en/instance.ts
@@ -93,6 +93,19 @@ export const instanceMessages = {
   "instanceShell.rightPanel.tabs.files": "Files",
   "instanceShell.rightPanel.tabs.status": "Status",
   "instanceShell.rightPanel.tabs.ariaLabel": "Right panel tabs",
+  "instanceShell.rightPanel.customize.toggle": "Customize right panel",
+  "instanceShell.rightPanel.customize.title": "Customize right panel",
+  "instanceShell.rightPanel.customize.description": "Show or hide tabs and status sections.",
+  "instanceShell.rightPanel.customize.reset": "Reset",
+  "instanceShell.rightPanel.customize.tabs": "Tabs",
+  "instanceShell.rightPanel.customize.statusSections": "Status sections",
+  "instanceShell.rightPanel.customize.dragToReorder": "Drag tabs or status sections to reorder.",
+  "instanceShell.rightPanel.customize.moveUp": "Up",
+  "instanceShell.rightPanel.customize.moveDown": "Down",
+  "instanceShell.rightPanel.customize.moveTabUp": "Move {label} tab up",
+  "instanceShell.rightPanel.customize.moveTabDown": "Move {label} tab down",
+  "instanceShell.rightPanel.customize.moveStatusSectionUp": "Move {label} status section up",
+  "instanceShell.rightPanel.customize.moveStatusSectionDown": "Move {label} status section down",
   "instanceShell.rightPanel.actions.refresh": "Refresh",
   "instanceShell.rightPanel.actions.save": "Save (Ctrl+S)",
   "instanceShell.rightPanel.actions.saveConfirm.message": "Do you want to save changes to \"{path}\" before switching?",
@@ -191,8 +204,8 @@ export const instanceMessages = {
 
   "instanceShell.yoloMode.noSessionSelected": "Select a session to configure Yolo mode.",
   "instanceShell.yoloMode.title": "Yolo mode",
-  "instanceShell.yoloMode.description": "Automatically approve permission requests for this session. Disabled by default.",
-  "instanceShell.yoloMode.badge": "Yolo mode",
+  "instanceShell.yoloMode.description": "Automatically approve permission requests for this session.",
+  "instanceShell.yoloMode.badge": "Yolo",
   "instanceShell.yoloMode.badgeAriaLabel": "Yolo mode enabled",
 
   "instanceShell.backgroundProcesses.empty": "No background processes.",
diff --git a/packages/ui/src/lib/i18n/messages/en/markdown.ts b/packages/ui/src/lib/i18n/messages/en/markdown.ts
index c7aea2cc..5a47fc0d 100644
--- a/packages/ui/src/lib/i18n/messages/en/markdown.ts
+++ b/packages/ui/src/lib/i18n/messages/en/markdown.ts
@@ -2,6 +2,8 @@ export const markdownMessages = {
   "markdown.codeBlock.copy.label": "Copy",
   "markdown.codeBlock.copy.copied": "Copied!",
   "markdown.codeBlock.copy.failed": "Failed",
+  "markdown.codeBlock.wrap.enable": "Enable word wrap",
+  "markdown.codeBlock.wrap.disable": "Disable word wrap",
 
   "markdown.copy": "Copy",
 } as const
diff --git a/packages/ui/src/lib/i18n/messages/en/messaging.ts b/packages/ui/src/lib/i18n/messages/en/messaging.ts
index b4e02141..d337618c 100644
--- a/packages/ui/src/lib/i18n/messages/en/messaging.ts
+++ b/packages/ui/src/lib/i18n/messages/en/messaging.ts
@@ -17,6 +17,7 @@ export const messagingMessages = {
   "messageSection.empty.tips.attachFilesPrefix": "Attach files with",
   "messageSection.loading.messages": "Loading messages...",
   "messageSection.loadError.title": "Could not load messages",
+  "messageSection.loadError.detail": "OpenCode did not return the session messages.",
   "messageSection.loadError.reload": "Reload messages",
   "messageSection.scroll.toFirstAriaLabel": "Scroll to first message",
   "messageSection.scroll.toLatestAriaLabel": "Scroll to latest message",
@@ -71,6 +72,8 @@ export const messagingMessages = {
   "messageBlock.usage.cacheRead": "Cache Read",
   "messageBlock.usage.cacheWrite": "Cache Write",
   "messageBlock.usage.cost": "Cost",
+  "messageBlock.usage.expandAriaLabel": "Expand token metrics",
+  "messageBlock.usage.collapseAriaLabel": "Collapse token metrics",
   "messageBlock.step.agentLabel": "Agent: {agent}",
   "messageBlock.step.modelLabel": "Model: {model}",
   "messageBlock.reasoning.thinkingLabel": "Thinking",
diff --git a/packages/ui/src/lib/i18n/messages/en/session.ts b/packages/ui/src/lib/i18n/messages/en/session.ts
index fa7a4021..50733e0d 100644
--- a/packages/ui/src/lib/i18n/messages/en/session.ts
+++ b/packages/ui/src/lib/i18n/messages/en/session.ts
@@ -15,6 +15,7 @@ export const sessionMessages = {
   "sessionList.status.working": "Working",
   "sessionList.status.compacting": "Compacting",
   "sessionList.status.idle": "Idle",
+  "sessionList.status.interrupted": "Interrupted",
   "sessionList.status.retrying": "Retrying",
   "sessionList.status.retryingIn": "Retrying in {seconds}s",
   "sessionList.status.retryTooltip": "{message} (Attempt {attempt})",
@@ -48,6 +49,10 @@ export const sessionMessages = {
   "sessionList.filter.placeholder": "Search sessions…",
   "sessionList.filter.ariaLabel": "Search sessions",
   "sessionList.loading.more": "Loading more sessions…",
+  "sessionList.loading.initial": "Loading sessions…",
+  "sessionList.loadError.title": "Unable to load sessions",
+  "sessionList.loadError.detail": "OpenCode did not return the session list.",
+  "sessionList.loadError.retry": "Retry",
   "sessionList.selection.selectAllLabel": "Select all",
   "sessionList.selection.selectAllAriaLabel": "Select all sessions",
   "sessionList.selection.clearLabel": "Clear",
diff --git a/packages/ui/src/lib/i18n/messages/en/settings.ts b/packages/ui/src/lib/i18n/messages/en/settings.ts
index fc408b69..7e79f5e0 100644
--- a/packages/ui/src/lib/i18n/messages/en/settings.ts
+++ b/packages/ui/src/lib/i18n/messages/en/settings.ts
@@ -56,6 +56,7 @@ export const settingsMessages = {
   "contextUsagePanel.labels.input": "Input",
   "contextUsagePanel.labels.output": "Output",
   "contextUsagePanel.labels.cost": "Cost",
+  "contextUsagePanel.included": "Included",
   "contextUsagePanel.labels.totalInput": "Total In",
   "contextUsagePanel.labels.totalOutput": "Total Out",
   "contextUsagePanel.labels.totalCost": "Total Cost",
@@ -64,6 +65,32 @@ export const settingsMessages = {
   "contextUsagePanel.labels.available": "Avail",
   "contextUsagePanel.unavailable": "--",
 
+  "providerUsage.title": "Usage",
+  "providerUsage.tooltip": "Usage and reset windows for the provider selected by the active session.",
+  "providerUsage.noSession": "Select a session to view plan usage.",
+  "providerUsage.loading": "Loading usage...",
+  "providerUsage.unsupported": "Usage is not available for this provider.",
+  "providerUsage.notConfigured": "No compatible subscription credential was found.",
+  "providerUsage.unavailable": "Usage is temporarily unavailable.",
+  "providerUsage.unavailableValue": "--",
+  "providerUsage.usedPercent": "{percent}% used",
+  "providerUsage.resets": "Resets {time}",
+  "providerUsage.progressLabel": "{window} plan usage",
+  "providerUsage.windows.fiveHours": "5 hours",
+  "providerUsage.windows.sevenDays": "7 days",
+  "providerUsage.windows.sevenDaysSonnet": "7 days · Sonnet",
+  "providerUsage.windows.sevenDaysOpus": "7 days · Opus",
+  "providerUsage.windows.weekly": "Weekly",
+  "providerUsage.windows.daily": "Daily",
+  "providerUsage.windows.monthly": "Monthly",
+  "providerUsage.windows.credits": "Credits",
+  "providerUsage.windows.billingCycle": "Billing cycle",
+  "providerUsage.windows.session": "Session",
+  "providerUsage.windows.premium": "Premium requests",
+  "providerUsage.windows.chat": "Chat",
+  "providerUsage.windows.completions": "Completions",
+  "providerUsage.windows.mcpTools": "MCP tools",
+
   "settings.title": "Settings",
   "settings.navigationAriaLabel": "Settings sections",
   "settings.close": "Close settings",
@@ -71,6 +98,16 @@ export const settingsMessages = {
   "settings.open.title": "Open settings",
   "settings.open.ariaLabel": "Open settings",
   "settings.nav.appearance": "Appearance",
+  "settings.nav.general": "General",
+  "settings.nav.chat": "Chat",
+  "settings.nav.voice": "Voice",
+  "settings.nav.connections": "Connections",
+  "settings.nav.runtime": "Runtime",
+  "settings.nav.advanced": "Advanced",
+  "settings.nav.about": "About",
+  "settings.general.language.subtitle": "Choose the language used throughout the application.",
+  "settings.behavior.holdLongAssistantReplies.title": "Hold long assistant replies",
+  "settings.behavior.holdLongAssistantReplies.subtitle": "Stop following automatically when a streaming reply grows beyond the viewport.",
   "settings.nav.notifications": "Notifications",
   "settings.nav.remote": "Remote Access",
   "settings.nav.speech": "Speech",
@@ -89,6 +126,16 @@ export const settingsMessages = {
   "settings.appearance.theme.option.system": "Match your operating system setting",
   "settings.appearance.theme.option.light": "Use the light appearance",
   "settings.appearance.theme.option.dark": "Use the dark appearance",
+  "settings.appearance.startup.title": "Startup",
+  "settings.appearance.startup.subtitle": "Choose what this device restores when CodeNomad starts.",
+  "settings.appearance.startup.restore.title": "Restore previous state",
+  "settings.appearance.startup.restore.subtitle": "Reopen workspace and sidecar tabs, active sessions, and unsent messages, and restore scroll positions, panel layout, window position, and zoom.",
+  "settings.appearance.startup.clear.title": "Saved startup state",
+  "settings.appearance.startup.clear.subtitle": "Remove saved tabs, drafts, scroll positions, and panel layout. CodeNomad and OpenCode data are not deleted.",
+  "settings.appearance.startup.clear.action": "Clear saved state",
+  "settings.appearance.startup.clearSuccess": "Saved startup state cleared.",
+  "settings.appearance.startup.clearError": "Could not clear the saved startup state.",
+  "settings.appearance.startup.updateError": "Could not update the startup restore setting.",
   "settings.section.notifications.title": "Notifications",
   "settings.section.notifications.subtitle": "Control OS-level notifications for session activity.",
   "settings.notifications.permission.granted": "Granted",
@@ -132,6 +179,18 @@ export const settingsMessages = {
   "settings.opencode.logLevel.option.info": "Info",
   "settings.opencode.logLevel.option.warn": "Warn",
   "settings.opencode.logLevel.option.error": "Error",
+  "settings.opencode.update.title": "OpenCode updates",
+  "settings.opencode.update.subtitle": "Check and install updates for the configured OpenCode binary.",
+  "settings.opencode.update.checking": "Checking for updates...",
+  "settings.opencode.update.checkFailed": "Could not check for OpenCode updates.",
+  "settings.opencode.update.retry": "Try again",
+  "settings.opencode.update.installed": "Installed version",
+  "settings.opencode.update.upToDate": "OpenCode is up to date.",
+  "settings.opencode.update.action": "Update to OpenCode {version}",
+  "settings.opencode.update.updating": "Updating OpenCode...",
+  "settings.opencode.update.requiresInstance": "Start a workspace with this binary to install the update.",
+  "settings.opencode.update.success": "OpenCode {version} is installed. New instances will use the updated version.",
+  "settings.opencode.update.failed": "The OpenCode update failed. Your installed version was not changed.",
   "settings.configFiles.title": "Config Files",
   "settings.configFiles.subtitle": "Edit allowlisted global configuration files on this server.",
   "settings.configFiles.selector.label": "File",
@@ -151,6 +210,7 @@ export const settingsMessages = {
   "settings.configFiles.confirmDiscard.cancelLabel": "Keep editing",
 
   "settings.providers.title": "Provider Authentication",
+  "settings.providers.target": "OpenCode instance: {workspace}",
   "settings.providers.subtitle": "Connect API keys or OAuth accounts for the active OpenCode instance.",
   "settings.providers.refresh": "Refresh",
   "settings.providers.selectProvider": "Select provider",
@@ -209,7 +269,7 @@ export const settingsMessages = {
 
 
   "settings.appearance.behavior.title": "Interaction",
-  "settings.appearance.behavior.subtitle": "Message, diff, and input defaults.",
+  "settings.appearance.behavior.subtitle": "Control message, tool, diagnostics, and usage detail together.",
   "settings.behavior.expansionPresets.ariaLabel": "Transcript detail presets",
   "settings.behavior.expansionPreset.minimal.title": "Minimal",
   "settings.behavior.expansionPreset.minimal.description": "Keep most generated detail tucked away until needed.",
@@ -267,6 +327,7 @@ export const settingsMessages = {
   "settings.speech.status.loading": "Checking configuration...",
   "settings.speech.status.configured": "Configured",
   "settings.speech.status.missing": "Missing API key",
+  "settings.speech.status.partial": "Partially configured",
   "settings.speech.status.error": "Speech service unavailable",
   "settings.speech.apiKey.title": "API key",
   "settings.speech.apiKey.subtitle": "Used for CodeNomad-managed speech requests.",
@@ -298,11 +359,44 @@ export const settingsMessages = {
   "settings.speech.testPlayback.stop": "Stop sample",
   "settings.speech.testPlayback.sample": "Thank you for using CodeNomad, your speech settings are working fine.",
   "settings.speech.testPlayback.note": "The test uses your current playback mode and format immediately. Save API key, base URL, model, or voice changes first if you want those reflected too.",
+  "settings.speech.testInput.action": "Test input",
+  "settings.speech.testInput.stop": "Stop recording",
+  "settings.speech.testInput.transcribing": "Transcribing",
+  "settings.speech.testInput.requesting": "Starting…",
+  "settings.speech.testInput.empty": "No speech detected",
   "settings.speech.save.action": "Save",
   "settings.speech.save.saving": "Saving...",
   "settings.speech.save.saved": "Saved",
   "settings.speech.save.unsaved": "Unsaved changes",
   "settings.speech.save.error": "Save failed",
+  "settings.speech.separateProviders.title": "Separate providers for input and output",
+  "settings.speech.separateProviders.subtitle": "Use different API keys and endpoints for voice input (STT) and output (TTS).",
+  "settings.speech.stt.section.title": "Voice Input (Speech-to-Text)",
+  "settings.speech.tts.section.title": "Voice Output (Text-to-Speech)",
+  "settings.speech.stt.apiKey.title": "Input API key",
+  "settings.speech.stt.apiKey.subtitle": "Used for speech-to-text transcription requests.",
+  "settings.speech.stt.apiKey.placeholder": "Enter a new input API key",
+  "settings.speech.stt.apiKey.storedNote": "A saved input API key is hidden. Enter a new value to replace it, or leave the field blank to keep it.",
+  "settings.speech.stt.apiKey.usingShared": "Using the shared API key. Enter a new key to override.",
+  "settings.speech.stt.apiKey.clearAction": "Clear saved input key",
+  "settings.speech.stt.apiKey.clearPending": "The saved input API key will be removed when you save.",
+  "settings.speech.stt.baseUrl.title": "Input base URL",
+  "settings.speech.stt.baseUrl.subtitle": "OpenAI-compatible endpoint for transcription requests.",
+  "settings.speech.stt.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.stt.model.title": "Input model",
+  "settings.speech.stt.model.subtitle": "Model used for speech-to-text.",
+  "settings.speech.tts.apiKey.title": "Output API key",
+  "settings.speech.tts.apiKey.subtitle": "Used for text-to-speech synthesis requests.",
+  "settings.speech.tts.apiKey.placeholder": "Enter a new output API key",
+  "settings.speech.tts.apiKey.storedNote": "A saved output API key is hidden. Enter a new value to replace it, or leave the field blank to keep it.",
+  "settings.speech.tts.apiKey.usingShared": "Using the shared API key. Enter a new key to override.",
+  "settings.speech.tts.apiKey.clearAction": "Clear saved output key",
+  "settings.speech.tts.apiKey.clearPending": "The saved output API key will be removed when you save.",
+  "settings.speech.tts.baseUrl.title": "Output base URL",
+  "settings.speech.tts.baseUrl.subtitle": "OpenAI-compatible endpoint for synthesis requests.",
+  "settings.speech.tts.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.tts.model.title": "Output model",
+  "settings.speech.tts.model.subtitle": "Model used for text-to-speech.",
   "settings.nav.sidecars": "SideCars",
   "settings.section.sidecars.eyebrow": "Server services",
   "settings.section.sidecars.title": "SideCars",
diff --git a/packages/ui/src/lib/i18n/messages/es/commands.ts b/packages/ui/src/lib/i18n/messages/es/commands.ts
index 10b42ff5..68e9c302 100644
--- a/packages/ui/src/lib/i18n/messages/es/commands.ts
+++ b/packages/ui/src/lib/i18n/messages/es/commands.ts
@@ -123,12 +123,12 @@ export const commandMessages = {
   "commands.diffViewUnified.keywords": "diff, unificada, vista",
 
   "commands.toolOutputsDefault.label": "Salidas de herramientas por defecto · {state}",
-  "commands.toolOutputsDefault.description": "Alternar la expansión por defecto de las salidas de herramientas",
-  "commands.toolOutputsDefault.keywords": "herramienta, salida, expandir, colapsar",
+  "commands.toolOutputsDefault.description": "Configurar la visibilidad por defecto de las salidas de herramientas",
+  "commands.toolOutputsDefault.keywords": "herramienta, salida, ocultar, expandir, colapsar",
 
   "commands.diagnosticsDefault.label": "Diagnósticos por defecto · {state}",
-  "commands.diagnosticsDefault.description": "Alternar la expansión por defecto de la salida de diagnósticos",
-  "commands.diagnosticsDefault.keywords": "diagnósticos, expandir, colapsar",
+  "commands.diagnosticsDefault.description": "Configurar la visibilidad por defecto de la salida de diagnósticos",
+  "commands.diagnosticsDefault.keywords": "diagnósticos, ocultar, expandir, colapsar",
 
   "commands.toolInputsVisibility.label": "Visibilidad de entradas de herramientas · {state}",
   "commands.toolInputsVisibility.description": "Configurar la visibilidad por defecto de los argumentos de entrada de llamadas de herramienta",
diff --git a/packages/ui/src/lib/i18n/messages/es/folderSelection.ts b/packages/ui/src/lib/i18n/messages/es/folderSelection.ts
index e6ad4872..65d228b5 100644
--- a/packages/ui/src/lib/i18n/messages/es/folderSelection.ts
+++ b/packages/ui/src/lib/i18n/messages/es/folderSelection.ts
@@ -17,10 +17,8 @@ export const folderSelectionMessages = {
   "folderSelection.recent.rename": "Renombrar workspace",
   "folderSelection.recent.remove": "Eliminar de recientes",
   "folderSelection.recent.openBadge": "Abierta",
-  "folderSelection.recent.alreadyOpenTitle": "Proyecto ya abierto",
-  "folderSelection.recent.alreadyOpenMessage": "Elige cómo abrir esta carpeta.",
+  "folderSelection.recent.openNewInstance": "Abrir una nueva instancia",
   "folderSelection.recent.switchToOpenProject": "Cambiar al proyecto abierto",
-  "folderSelection.recent.openAnotherInstance": "Abrir otra instancia",
 
   "folderSelection.browse.title": "Buscar carpeta",
   "folderSelection.browse.subtitle": "Selecciona cualquier carpeta en tu ordenador",
diff --git a/packages/ui/src/lib/i18n/messages/es/instance.ts b/packages/ui/src/lib/i18n/messages/es/instance.ts
index 39c11e61..a8237d41 100644
--- a/packages/ui/src/lib/i18n/messages/es/instance.ts
+++ b/packages/ui/src/lib/i18n/messages/es/instance.ts
@@ -93,6 +93,19 @@ export const instanceMessages = {
   "instanceShell.rightPanel.tabs.files": "Archivos",
   "instanceShell.rightPanel.tabs.status": "Estado",
   "instanceShell.rightPanel.tabs.ariaLabel": "Pestañas del panel derecho",
+  "instanceShell.rightPanel.customize.toggle": "Personalizar panel derecho",
+  "instanceShell.rightPanel.customize.title": "Personalizar panel derecho",
+  "instanceShell.rightPanel.customize.description": "Muestra u oculta pestañas y secciones de estado.",
+  "instanceShell.rightPanel.customize.reset": "Restablecer",
+  "instanceShell.rightPanel.customize.tabs": "Pestañas",
+  "instanceShell.rightPanel.customize.statusSections": "Secciones de estado",
+  "instanceShell.rightPanel.customize.dragToReorder": "Arrastra pestañas o secciones de estado para reordenarlas.",
+  "instanceShell.rightPanel.customize.moveUp": "Subir",
+  "instanceShell.rightPanel.customize.moveDown": "Bajar",
+  "instanceShell.rightPanel.customize.moveTabUp": "Subir pestaña {label}",
+  "instanceShell.rightPanel.customize.moveTabDown": "Bajar pestaña {label}",
+  "instanceShell.rightPanel.customize.moveStatusSectionUp": "Subir sección de estado {label}",
+  "instanceShell.rightPanel.customize.moveStatusSectionDown": "Bajar sección de estado {label}",
   "instanceShell.rightPanel.actions.refresh": "Actualizar",
   "instanceShell.rightPanel.actions.save": "Guardar (Ctrl+S)",
   "instanceShell.rightPanel.actions.saveConfirm.message": "¿Deseas guardar los cambios en \"{path}\" antes de cambiar?",
@@ -167,8 +180,8 @@ export const instanceMessages = {
 
   "instanceShell.yoloMode.noSessionSelected": "Selecciona una sesion para configurar el modo yolo.",
   "instanceShell.yoloMode.title": "Modo yolo",
-  "instanceShell.yoloMode.description": "Aprueba automaticamente las solicitudes de permiso de esta sesion. Esta desactivado por defecto.",
-  "instanceShell.yoloMode.badge": "Modo yolo",
+  "instanceShell.yoloMode.description": "Aprueba automaticamente las solicitudes de permiso de esta sesion.",
+  "instanceShell.yoloMode.badge": "Yolo",
   "instanceShell.yoloMode.badgeAriaLabel": "Modo yolo activado",
 
   "instanceShell.backgroundProcesses.empty": "No hay procesos en segundo plano.",
diff --git a/packages/ui/src/lib/i18n/messages/es/markdown.ts b/packages/ui/src/lib/i18n/messages/es/markdown.ts
index f92d46b9..f0b89ac0 100644
--- a/packages/ui/src/lib/i18n/messages/es/markdown.ts
+++ b/packages/ui/src/lib/i18n/messages/es/markdown.ts
@@ -2,6 +2,8 @@ export const markdownMessages = {
   "markdown.codeBlock.copy.label": "Copiar",
   "markdown.codeBlock.copy.copied": "¡Copiado!",
   "markdown.codeBlock.copy.failed": "Error",
+  "markdown.codeBlock.wrap.enable": "Activar ajuste de línea",
+  "markdown.codeBlock.wrap.disable": "Desactivar ajuste de línea",
 
   "markdown.copy": "Copiar",
 } as const
diff --git a/packages/ui/src/lib/i18n/messages/es/messaging.ts b/packages/ui/src/lib/i18n/messages/es/messaging.ts
index 3582ec38..43d6530b 100644
--- a/packages/ui/src/lib/i18n/messages/es/messaging.ts
+++ b/packages/ui/src/lib/i18n/messages/es/messaging.ts
@@ -17,6 +17,7 @@ export const messagingMessages = {
   "messageSection.empty.tips.attachFilesPrefix": "Adjunta archivos con",
   "messageSection.loading.messages": "Cargando mensajes...",
   "messageSection.loadError.title": "No se pudieron cargar los mensajes",
+  "messageSection.loadError.detail": "OpenCode no devolvió los mensajes de la sesión.",
   "messageSection.loadError.reload": "Recargar mensajes",
   "messageSection.scroll.toFirstAriaLabel": "Desplazarse al primer mensaje",
   "messageSection.scroll.toLatestAriaLabel": "Desplazarse al último mensaje",
@@ -73,6 +74,8 @@ export const messagingMessages = {
   "messageBlock.usage.cacheRead": "Lectura de cache",
   "messageBlock.usage.cacheWrite": "Escritura de cache",
   "messageBlock.usage.cost": "Costo",
+  "messageBlock.usage.expandAriaLabel": "Expandir métricas de tokens",
+  "messageBlock.usage.collapseAriaLabel": "Contraer métricas de tokens",
   "messageBlock.step.agentLabel": "Agente: {agent}",
   "messageBlock.step.modelLabel": "Modelo: {model}",
   "messageBlock.reasoning.thinkingLabel": "Pensamiento",
diff --git a/packages/ui/src/lib/i18n/messages/es/session.ts b/packages/ui/src/lib/i18n/messages/es/session.ts
index 7ce3e3eb..d09ef502 100644
--- a/packages/ui/src/lib/i18n/messages/es/session.ts
+++ b/packages/ui/src/lib/i18n/messages/es/session.ts
@@ -15,6 +15,7 @@ export const sessionMessages = {
   "sessionList.status.working": "Trabajando",
   "sessionList.status.compacting": "Compactando",
   "sessionList.status.idle": "Inactiva",
+  "sessionList.status.interrupted": "Interrumpido",
   "sessionList.status.retrying": "Reintentando",
   "sessionList.status.retryingIn": "Reintentando en {seconds}s",
   "sessionList.status.retryTooltip": "{message} (Intento {attempt})",
@@ -48,6 +49,10 @@ export const sessionMessages = {
   "sessionList.filter.placeholder": "Buscar sesiones…",
   "sessionList.filter.ariaLabel": "Buscar sesiones",
   "sessionList.loading.more": "Cargando más sesiones…",
+  "sessionList.loading.initial": "Cargando sesiones…",
+  "sessionList.loadError.title": "No se pudieron cargar las sesiones",
+  "sessionList.loadError.detail": "OpenCode no devolvió la lista de sesiones.",
+  "sessionList.loadError.retry": "Reintentar",
   "sessionList.selection.selectAllLabel": "Seleccionar todo",
   "sessionList.selection.selectAllAriaLabel": "Seleccionar todas las sesiones",
   "sessionList.selection.clearLabel": "Limpiar",
diff --git a/packages/ui/src/lib/i18n/messages/es/settings.ts b/packages/ui/src/lib/i18n/messages/es/settings.ts
index 1e9a3098..268c3062 100644
--- a/packages/ui/src/lib/i18n/messages/es/settings.ts
+++ b/packages/ui/src/lib/i18n/messages/es/settings.ts
@@ -56,6 +56,7 @@ export const settingsMessages = {
   "contextUsagePanel.labels.input": "Entrada",
   "contextUsagePanel.labels.output": "Salida",
   "contextUsagePanel.labels.cost": "Costo",
+  "contextUsagePanel.included": "Incluido",
   "contextUsagePanel.labels.totalInput": "Entrada total",
   "contextUsagePanel.labels.totalOutput": "Salida total",
   "contextUsagePanel.labels.totalCost": "Costo total",
@@ -64,6 +65,32 @@ export const settingsMessages = {
   "contextUsagePanel.labels.available": "Disp.",
   "contextUsagePanel.unavailable": "--",
 
+  "providerUsage.title": "Uso",
+  "providerUsage.tooltip": "Uso y ventanas de restablecimiento del proveedor seleccionado en la sesión activa.",
+  "providerUsage.noSession": "Selecciona una sesión para ver el uso del plan.",
+  "providerUsage.loading": "Cargando uso...",
+  "providerUsage.unsupported": "El uso no está disponible para este proveedor.",
+  "providerUsage.notConfigured": "No se encontraron credenciales de suscripción compatibles.",
+  "providerUsage.unavailable": "El uso no está disponible temporalmente.",
+  "providerUsage.unavailableValue": "--",
+  "providerUsage.usedPercent": "{percent} % usado",
+  "providerUsage.resets": "Se restablece {time}",
+  "providerUsage.progressLabel": "Uso del plan {window}",
+  "providerUsage.windows.fiveHours": "5 horas",
+  "providerUsage.windows.sevenDays": "7 días",
+  "providerUsage.windows.sevenDaysSonnet": "7 días · Sonnet",
+  "providerUsage.windows.sevenDaysOpus": "7 días · Opus",
+  "providerUsage.windows.weekly": "Semanal",
+  "providerUsage.windows.daily": "Diario",
+  "providerUsage.windows.monthly": "Mensual",
+  "providerUsage.windows.credits": "Créditos",
+  "providerUsage.windows.billingCycle": "Ciclo de facturación",
+  "providerUsage.windows.session": "Sesión",
+  "providerUsage.windows.premium": "Solicitudes premium",
+  "providerUsage.windows.chat": "Chat",
+  "providerUsage.windows.completions": "Completados",
+  "providerUsage.windows.mcpTools": "Herramientas MCP",
+
   "settings.title": "Configuración",
   "settings.navigationAriaLabel": "Secciones de configuración",
   "settings.close": "Cerrar configuración",
@@ -71,6 +98,16 @@ export const settingsMessages = {
   "settings.open.title": "Abrir configuración",
   "settings.open.ariaLabel": "Abrir configuración",
   "settings.nav.appearance": "Apariencia",
+  "settings.nav.general": "General",
+  "settings.nav.chat": "Chat",
+  "settings.nav.voice": "Voz",
+  "settings.nav.connections": "Conexiones",
+  "settings.nav.runtime": "Entorno de ejecución",
+  "settings.nav.advanced": "Avanzado",
+  "settings.nav.about": "Acerca de",
+  "settings.general.language.subtitle": "Elige el idioma utilizado en toda la aplicación.",
+  "settings.behavior.holdLongAssistantReplies.title": "Retener respuestas largas del asistente",
+  "settings.behavior.holdLongAssistantReplies.subtitle": "Deja de seguir automáticamente cuando una respuesta en curso supera la ventana.",
   "settings.nav.notifications": "Notificaciones",
   "settings.nav.remote": "Acceso remoto",
   "settings.nav.speech": "Voz",
@@ -89,6 +126,16 @@ export const settingsMessages = {
   "settings.appearance.theme.option.system": "Coincidir con la configuración del sistema operativo",
   "settings.appearance.theme.option.light": "Usar apariencia clara",
   "settings.appearance.theme.option.dark": "Usar apariencia oscura",
+  "settings.appearance.startup.title": "Inicio",
+  "settings.appearance.startup.subtitle": "Elige qué restaura este dispositivo al iniciar CodeNomad.",
+  "settings.appearance.startup.restore.title": "Restaurar el estado anterior",
+  "settings.appearance.startup.restore.subtitle": "Volver a abrir las pestañas de espacios de trabajo y sidecars, las sesiones activas y los mensajes no enviados, y restaurar las posiciones de desplazamiento, el diseño de paneles, la posición de la ventana y el zoom.",
+  "settings.appearance.startup.clear.title": "Estado de inicio guardado",
+  "settings.appearance.startup.clear.subtitle": "Elimina pestañas, borradores, posiciones de desplazamiento y el diseño de paneles guardados. No se eliminan datos de CodeNomad ni de OpenCode.",
+  "settings.appearance.startup.clear.action": "Borrar estado guardado",
+  "settings.appearance.startup.clearSuccess": "Se borró el estado de inicio guardado.",
+  "settings.appearance.startup.clearError": "No se pudo borrar el estado de inicio guardado.",
+  "settings.appearance.startup.updateError": "No se pudo actualizar el ajuste de restauración al inicio.",
   "settings.section.notifications.title": "Notificaciones",
   "settings.section.notifications.subtitle": "Controla las notificaciones del sistema para la actividad de sesiones.",
   "settings.notifications.permission.granted": "Concedido",
@@ -132,6 +179,18 @@ export const settingsMessages = {
   "settings.opencode.logLevel.option.info": "Informacion",
   "settings.opencode.logLevel.option.warn": "Advertencia",
   "settings.opencode.logLevel.option.error": "Error",
+  "settings.opencode.update.title": "Actualizaciones de OpenCode",
+  "settings.opencode.update.subtitle": "Comprueba e instala actualizaciones para el binario de OpenCode configurado.",
+  "settings.opencode.update.checking": "Buscando actualizaciones...",
+  "settings.opencode.update.checkFailed": "No se pudieron comprobar las actualizaciones de OpenCode.",
+  "settings.opencode.update.retry": "Reintentar",
+  "settings.opencode.update.installed": "Versión instalada",
+  "settings.opencode.update.upToDate": "OpenCode está actualizado.",
+  "settings.opencode.update.action": "Actualizar a OpenCode {version}",
+  "settings.opencode.update.updating": "Actualizando OpenCode...",
+  "settings.opencode.update.requiresInstance": "Inicia un espacio de trabajo con este binario para instalar la actualización.",
+  "settings.opencode.update.success": "OpenCode {version} está instalado. Las nuevas instancias usarán la versión actualizada.",
+  "settings.opencode.update.failed": "La actualización de OpenCode falló. La versión instalada no cambió.",
   "settings.configFiles.title": "Archivos de configuración",
   "settings.configFiles.subtitle": "Edita archivos de configuración global permitidos en este servidor.",
   "settings.configFiles.selector.label": "Archivo",
@@ -151,6 +210,7 @@ export const settingsMessages = {
   "settings.configFiles.confirmDiscard.cancelLabel": "Seguir editando",
 
   "settings.providers.title": "Autenticación de proveedores",
+  "settings.providers.target": "Instancia de OpenCode: {workspace}",
   "settings.providers.subtitle": "Conecta claves API o cuentas OAuth para la instancia activa de OpenCode.",
   "settings.providers.refresh": "Actualizar",
   "settings.providers.selectProvider": "Seleccionar proveedor",
@@ -208,8 +268,8 @@ export const settingsMessages = {
   "settings.providers.errors.envDisconnectUnavailable": "Este proveedor está configurado desde variables de entorno y no se puede desconectar desde la UI.",
 
   "settings.appearance.behavior.title": "Interacción",
-  "settings.appearance.behavior.subtitle": "Valores predeterminados de mensajes, diffs y entrada.",
-  "settings.behavior.expansionPresets.ariaLabel": "Transcript detail presets",
+  "settings.appearance.behavior.subtitle": "Controla conjuntamente el detalle de mensajes, herramientas, diagnosticos y uso.",
+  "settings.behavior.expansionPresets.ariaLabel": "Preajustes de detalle de conversacion",
   "settings.behavior.expansionPreset.minimal.title": "Minimal",
   "settings.behavior.expansionPreset.minimal.description": "Keep most generated detail tucked away until needed.",
   "settings.behavior.expansionPreset.balanced.title": "Balanced",
@@ -266,6 +326,7 @@ export const settingsMessages = {
   "settings.speech.status.loading": "Comprobando configuración...",
   "settings.speech.status.configured": "Configurado",
   "settings.speech.status.missing": "Falta la clave API",
+  "settings.speech.status.partial": "Parcialmente configurado",
   "settings.speech.status.error": "Servicio de voz no disponible",
   "settings.speech.apiKey.title": "Clave API",
   "settings.speech.apiKey.subtitle": "Se usa para las solicitudes de voz gestionadas por CodeNomad.",
@@ -297,11 +358,44 @@ export const settingsMessages = {
   "settings.speech.testPlayback.stop": "Detener muestra",
   "settings.speech.testPlayback.sample": "Gracias por usar CodeNomad, tu configuración de voz funciona correctamente.",
   "settings.speech.testPlayback.note": "La prueba usa de inmediato el modo y formato actuales. Guarda primero los cambios de clave API, URL base, modelo o voz si también quieres probarlos.",
+  "settings.speech.testInput.action": "Probar entrada",
+  "settings.speech.testInput.stop": "Detener grabación",
+  "settings.speech.testInput.transcribing": "Transcribiendo",
+  "settings.speech.testInput.requesting": "Iniciando…",
+  "settings.speech.testInput.empty": "No se detectó voz",
   "settings.speech.save.action": "Guardar",
   "settings.speech.save.saving": "Guardando...",
   "settings.speech.save.saved": "Guardado",
   "settings.speech.save.unsaved": "Cambios sin guardar",
   "settings.speech.save.error": "Error al guardar",
+  "settings.speech.separateProviders.title": "Proveedores separados para entrada y salida",
+  "settings.speech.separateProviders.subtitle": "Usar diferentes claves API y endpoints para entrada de voz (STT) y salida (TTS).",
+  "settings.speech.stt.section.title": "Entrada de voz (Voz a texto)",
+  "settings.speech.tts.section.title": "Salida de voz (Texto a voz)",
+  "settings.speech.stt.apiKey.title": "Clave API de entrada",
+  "settings.speech.stt.apiKey.subtitle": "Usada para solicitudes de voz a texto.",
+  "settings.speech.stt.apiKey.placeholder": "Introduce una nueva clave API de entrada",
+  "settings.speech.stt.apiKey.storedNote": "Hay una clave API de entrada guardada y oculta. Introduce un nuevo valor para reemplazarla.",
+  "settings.speech.stt.apiKey.usingShared": "Usando la clave API compartida. Introduce una nueva para reemplazarla.",
+  "settings.speech.stt.apiKey.clearAction": "Borrar clave de entrada guardada",
+  "settings.speech.stt.apiKey.clearPending": "La clave API de entrada guardada se eliminará al guardar.",
+  "settings.speech.stt.baseUrl.title": "URL base de entrada",
+  "settings.speech.stt.baseUrl.subtitle": "Endpoint compatible con OpenAI para transcripción.",
+  "settings.speech.stt.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.stt.model.title": "Modelo de entrada",
+  "settings.speech.stt.model.subtitle": "Modelo usado para voz a texto.",
+  "settings.speech.tts.apiKey.title": "Clave API de salida",
+  "settings.speech.tts.apiKey.subtitle": "Usada para solicitudes de texto a voz.",
+  "settings.speech.tts.apiKey.placeholder": "Introduce una nueva clave API de salida",
+  "settings.speech.tts.apiKey.storedNote": "Hay una clave API de salida guardada y oculta. Introduce un nuevo valor para reemplazarla.",
+  "settings.speech.tts.apiKey.usingShared": "Usando la clave API compartida. Introduce una nueva para reemplazarla.",
+  "settings.speech.tts.apiKey.clearAction": "Borrar clave de salida guardada",
+  "settings.speech.tts.apiKey.clearPending": "La clave API de salida guardada se eliminará al guardar.",
+  "settings.speech.tts.baseUrl.title": "URL base de salida",
+  "settings.speech.tts.baseUrl.subtitle": "Endpoint compatible con OpenAI para síntesis.",
+  "settings.speech.tts.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.tts.model.title": "Modelo de salida",
+  "settings.speech.tts.model.subtitle": "Modelo usado para texto a voz.",
   "settings.nav.sidecars": "SideCars",
   "settings.section.sidecars.eyebrow": "Servicios del servidor",
   "settings.section.sidecars.title": "SideCars",
diff --git a/packages/ui/src/lib/i18n/messages/fr/commands.ts b/packages/ui/src/lib/i18n/messages/fr/commands.ts
index 6fbd59c0..f846bc88 100644
--- a/packages/ui/src/lib/i18n/messages/fr/commands.ts
+++ b/packages/ui/src/lib/i18n/messages/fr/commands.ts
@@ -123,12 +123,12 @@ export const commandMessages = {
   "commands.diffViewUnified.keywords": "diff, unifiée, vue",
 
   "commands.toolOutputsDefault.label": "Sorties d'outil par défaut · {state}",
-  "commands.toolOutputsDefault.description": "Choisir l'ouverture par défaut des sorties d'outil",
-  "commands.toolOutputsDefault.keywords": "outil, sortie, développer, réduire",
+  "commands.toolOutputsDefault.description": "Choisir la visibilité par défaut des sorties d'outil",
+  "commands.toolOutputsDefault.keywords": "outil, sortie, masquer, développer, réduire",
 
   "commands.diagnosticsDefault.label": "Diagnostics par défaut · {state}",
-  "commands.diagnosticsDefault.description": "Choisir l'ouverture par défaut de la sortie des diagnostics",
-  "commands.diagnosticsDefault.keywords": "diagnostics, développer, réduire",
+  "commands.diagnosticsDefault.description": "Choisir la visibilité par défaut de la sortie des diagnostics",
+  "commands.diagnosticsDefault.keywords": "diagnostics, masquer, développer, réduire",
 
   "commands.toolInputsVisibility.label": "Visibilité des entrées d'outil · {state}",
   "commands.toolInputsVisibility.description": "Définir la visibilité par défaut des arguments d'entrée des appels d'outil",
diff --git a/packages/ui/src/lib/i18n/messages/fr/folderSelection.ts b/packages/ui/src/lib/i18n/messages/fr/folderSelection.ts
index dd6de486..3190c23c 100644
--- a/packages/ui/src/lib/i18n/messages/fr/folderSelection.ts
+++ b/packages/ui/src/lib/i18n/messages/fr/folderSelection.ts
@@ -17,10 +17,8 @@ export const folderSelectionMessages = {
   "folderSelection.recent.rename": "Renommer l'espace de travail",
   "folderSelection.recent.remove": "Retirer des récents",
   "folderSelection.recent.openBadge": "Ouvert",
-  "folderSelection.recent.alreadyOpenTitle": "Projet déjà ouvert",
-  "folderSelection.recent.alreadyOpenMessage": "Choisissez comment ouvrir ce dossier.",
+  "folderSelection.recent.openNewInstance": "Ouvrir une nouvelle instance",
   "folderSelection.recent.switchToOpenProject": "Basculer vers le projet ouvert",
-  "folderSelection.recent.openAnotherInstance": "Ouvrir une autre instance",
 
   "folderSelection.browse.title": "Parcourir un dossier",
   "folderSelection.browse.subtitle": "Sélectionnez n'importe quel dossier sur votre ordinateur",
diff --git a/packages/ui/src/lib/i18n/messages/fr/instance.ts b/packages/ui/src/lib/i18n/messages/fr/instance.ts
index f47ec3f1..87b84b63 100644
--- a/packages/ui/src/lib/i18n/messages/fr/instance.ts
+++ b/packages/ui/src/lib/i18n/messages/fr/instance.ts
@@ -93,6 +93,19 @@ export const instanceMessages = {
   "instanceShell.rightPanel.tabs.files": "Fichiers",
   "instanceShell.rightPanel.tabs.status": "Statut",
   "instanceShell.rightPanel.tabs.ariaLabel": "Onglets du panneau droit",
+  "instanceShell.rightPanel.customize.toggle": "Personnaliser le panneau droit",
+  "instanceShell.rightPanel.customize.title": "Personnaliser le panneau droit",
+  "instanceShell.rightPanel.customize.description": "Afficher ou masquer les onglets et sections de statut.",
+  "instanceShell.rightPanel.customize.reset": "Réinitialiser",
+  "instanceShell.rightPanel.customize.tabs": "Onglets",
+  "instanceShell.rightPanel.customize.statusSections": "Sections de statut",
+  "instanceShell.rightPanel.customize.dragToReorder": "Faites glisser les onglets ou sections de statut pour les réordonner.",
+  "instanceShell.rightPanel.customize.moveUp": "Monter",
+  "instanceShell.rightPanel.customize.moveDown": "Descendre",
+  "instanceShell.rightPanel.customize.moveTabUp": "Monter l'onglet {label}",
+  "instanceShell.rightPanel.customize.moveTabDown": "Descendre l'onglet {label}",
+  "instanceShell.rightPanel.customize.moveStatusSectionUp": "Monter la section de statut {label}",
+  "instanceShell.rightPanel.customize.moveStatusSectionDown": "Descendre la section de statut {label}",
   "instanceShell.rightPanel.actions.refresh": "Actualiser",
   "instanceShell.rightPanel.actions.save": "Enregistrer (Ctrl+S)",
   "instanceShell.rightPanel.actions.saveConfirm.message": "Voulez-vous enregistrer les modifications de \"{path}\" avant de changer ?",
@@ -167,8 +180,8 @@ export const instanceMessages = {
 
   "instanceShell.yoloMode.noSessionSelected": "Selectionnez une session pour configurer le mode yolo.",
   "instanceShell.yoloMode.title": "Mode yolo",
-  "instanceShell.yoloMode.description": "Approuve automatiquement les demandes d'autorisation pour cette session. Desactive par defaut.",
-  "instanceShell.yoloMode.badge": "Mode yolo",
+  "instanceShell.yoloMode.description": "Approuve automatiquement les demandes d'autorisation pour cette session.",
+  "instanceShell.yoloMode.badge": "Yolo",
   "instanceShell.yoloMode.badgeAriaLabel": "Mode yolo active",
 
   "instanceShell.backgroundProcesses.empty": "Aucun processus en arrière-plan.",
diff --git a/packages/ui/src/lib/i18n/messages/fr/markdown.ts b/packages/ui/src/lib/i18n/messages/fr/markdown.ts
index 42a6915a..c8766d12 100644
--- a/packages/ui/src/lib/i18n/messages/fr/markdown.ts
+++ b/packages/ui/src/lib/i18n/messages/fr/markdown.ts
@@ -2,6 +2,8 @@ export const markdownMessages = {
   "markdown.codeBlock.copy.label": "Copier",
   "markdown.codeBlock.copy.copied": "Copié !",
   "markdown.codeBlock.copy.failed": "Échec",
+  "markdown.codeBlock.wrap.enable": "Activer le retour à la ligne",
+  "markdown.codeBlock.wrap.disable": "Désactiver le retour à la ligne",
 
   "markdown.copy": "Copier",
 } as const
diff --git a/packages/ui/src/lib/i18n/messages/fr/messaging.ts b/packages/ui/src/lib/i18n/messages/fr/messaging.ts
index a42be907..5ae20972 100644
--- a/packages/ui/src/lib/i18n/messages/fr/messaging.ts
+++ b/packages/ui/src/lib/i18n/messages/fr/messaging.ts
@@ -17,6 +17,7 @@ export const messagingMessages = {
   "messageSection.empty.tips.attachFilesPrefix": "Joindre des fichiers avec",
   "messageSection.loading.messages": "Chargement des messages...",
   "messageSection.loadError.title": "Impossible de charger les messages",
+  "messageSection.loadError.detail": "OpenCode n'a pas renvoyé les messages de la session.",
   "messageSection.loadError.reload": "Recharger les messages",
   "messageSection.scroll.toFirstAriaLabel": "Aller au premier message",
   "messageSection.scroll.toLatestAriaLabel": "Aller au dernier message",
@@ -73,6 +74,8 @@ export const messagingMessages = {
   "messageBlock.usage.cacheRead": "Lecture du cache",
   "messageBlock.usage.cacheWrite": "Écriture du cache",
   "messageBlock.usage.cost": "Coût",
+  "messageBlock.usage.expandAriaLabel": "Développer les métriques de tokens",
+  "messageBlock.usage.collapseAriaLabel": "Réduire les métriques de tokens",
   "messageBlock.step.agentLabel": "Agent : {agent}",
   "messageBlock.step.modelLabel": "Modèle : {model}",
   "messageBlock.reasoning.thinkingLabel": "Réflexion",
diff --git a/packages/ui/src/lib/i18n/messages/fr/session.ts b/packages/ui/src/lib/i18n/messages/fr/session.ts
index 5273f0fe..ae1c223c 100644
--- a/packages/ui/src/lib/i18n/messages/fr/session.ts
+++ b/packages/ui/src/lib/i18n/messages/fr/session.ts
@@ -15,6 +15,7 @@ export const sessionMessages = {
   "sessionList.status.working": "En cours",
   "sessionList.status.compacting": "Compactage",
   "sessionList.status.idle": "Inactif",
+  "sessionList.status.interrupted": "Interrompu",
   "sessionList.status.retrying": "Nouvelle tentative",
   "sessionList.status.retryingIn": "Nouvelle tentative dans {seconds}s",
   "sessionList.status.retryTooltip": "{message} (Tentative {attempt})",
@@ -48,6 +49,10 @@ export const sessionMessages = {
   "sessionList.filter.placeholder": "Rechercher des sessions…",
   "sessionList.filter.ariaLabel": "Rechercher des sessions",
   "sessionList.loading.more": "Chargement de plus de sessions…",
+  "sessionList.loading.initial": "Chargement des sessions…",
+  "sessionList.loadError.title": "Impossible de charger les sessions",
+  "sessionList.loadError.detail": "OpenCode n'a pas renvoyé la liste des sessions.",
+  "sessionList.loadError.retry": "Réessayer",
   "sessionList.selection.selectAllLabel": "Tout sélectionner",
   "sessionList.selection.selectAllAriaLabel": "Sélectionner toutes les sessions",
   "sessionList.selection.clearLabel": "Effacer",
diff --git a/packages/ui/src/lib/i18n/messages/fr/settings.ts b/packages/ui/src/lib/i18n/messages/fr/settings.ts
index a8878939..65c924f7 100644
--- a/packages/ui/src/lib/i18n/messages/fr/settings.ts
+++ b/packages/ui/src/lib/i18n/messages/fr/settings.ts
@@ -56,6 +56,7 @@ export const settingsMessages = {
   "contextUsagePanel.labels.input": "Entrée",
   "contextUsagePanel.labels.output": "Sortie",
   "contextUsagePanel.labels.cost": "Coût",
+  "contextUsagePanel.included": "Inclus",
   "contextUsagePanel.labels.totalInput": "Entrée totale",
   "contextUsagePanel.labels.totalOutput": "Sortie totale",
   "contextUsagePanel.labels.totalCost": "Coût total",
@@ -64,6 +65,32 @@ export const settingsMessages = {
   "contextUsagePanel.labels.available": "Dispo",
   "contextUsagePanel.unavailable": "--",
 
+  "providerUsage.title": "Utilisation",
+  "providerUsage.tooltip": "Utilisation et fenêtres de réinitialisation du fournisseur sélectionné par la session active.",
+  "providerUsage.noSession": "Sélectionnez une session pour afficher l'utilisation du forfait.",
+  "providerUsage.loading": "Chargement de l'utilisation...",
+  "providerUsage.unsupported": "L'utilisation n'est pas disponible pour ce fournisseur.",
+  "providerUsage.notConfigured": "Aucun identifiant d'abonnement compatible n'a été trouvé.",
+  "providerUsage.unavailable": "L'utilisation est temporairement indisponible.",
+  "providerUsage.unavailableValue": "--",
+  "providerUsage.usedPercent": "{percent} % utilisé",
+  "providerUsage.resets": "Réinitialisation {time}",
+  "providerUsage.progressLabel": "Utilisation du forfait {window}",
+  "providerUsage.windows.fiveHours": "5 heures",
+  "providerUsage.windows.sevenDays": "7 jours",
+  "providerUsage.windows.sevenDaysSonnet": "7 jours · Sonnet",
+  "providerUsage.windows.sevenDaysOpus": "7 jours · Opus",
+  "providerUsage.windows.weekly": "Hebdomadaire",
+  "providerUsage.windows.daily": "Quotidien",
+  "providerUsage.windows.monthly": "Mensuel",
+  "providerUsage.windows.credits": "Crédits",
+  "providerUsage.windows.billingCycle": "Cycle de facturation",
+  "providerUsage.windows.session": "Session",
+  "providerUsage.windows.premium": "Requêtes premium",
+  "providerUsage.windows.chat": "Chat",
+  "providerUsage.windows.completions": "Complétions",
+  "providerUsage.windows.mcpTools": "Outils MCP",
+
   "settings.title": "Paramètres",
   "settings.navigationAriaLabel": "Sections des paramètres",
   "settings.close": "Fermer les paramètres",
@@ -71,6 +98,16 @@ export const settingsMessages = {
   "settings.open.title": "Ouvrir les paramètres",
   "settings.open.ariaLabel": "Ouvrir les paramètres",
   "settings.nav.appearance": "Apparence",
+  "settings.nav.general": "Général",
+  "settings.nav.chat": "Chat",
+  "settings.nav.voice": "Voix",
+  "settings.nav.connections": "Connexions",
+  "settings.nav.runtime": "Exécution",
+  "settings.nav.advanced": "Avancé",
+  "settings.nav.about": "À propos",
+  "settings.general.language.subtitle": "Choisissez la langue utilisée dans toute l'application.",
+  "settings.behavior.holdLongAssistantReplies.title": "Suspendre le suivi des longues réponses",
+  "settings.behavior.holdLongAssistantReplies.subtitle": "Arrêter le suivi automatique lorsqu'une réponse en cours dépasse la fenêtre.",
   "settings.nav.notifications": "Notifications",
   "settings.nav.remote": "Accès distant",
   "settings.nav.speech": "Voix",
@@ -89,6 +126,16 @@ export const settingsMessages = {
   "settings.appearance.theme.option.system": "Suivre le réglage de votre système d'exploitation",
   "settings.appearance.theme.option.light": "Utiliser l'apparence claire",
   "settings.appearance.theme.option.dark": "Utiliser l'apparence sombre",
+  "settings.appearance.startup.title": "Démarrage",
+  "settings.appearance.startup.subtitle": "Choisissez ce que cet appareil restaure au démarrage de CodeNomad.",
+  "settings.appearance.startup.restore.title": "Restaurer l’état précédent",
+  "settings.appearance.startup.restore.subtitle": "Rouvrir les onglets d’espaces de travail et de sidecars, les sessions actives et les messages non envoyés, et restaurer les positions de défilement, la disposition des panneaux, la position de la fenêtre et le zoom.",
+  "settings.appearance.startup.clear.title": "État de démarrage enregistré",
+  "settings.appearance.startup.clear.subtitle": "Supprime les onglets, brouillons, positions de défilement et la disposition des panneaux enregistrés. Les données CodeNomad et OpenCode ne sont pas supprimées.",
+  "settings.appearance.startup.clear.action": "Effacer l’état enregistré",
+  "settings.appearance.startup.clearSuccess": "L’état de démarrage enregistré a été effacé.",
+  "settings.appearance.startup.clearError": "Impossible d’effacer l’état de démarrage enregistré.",
+  "settings.appearance.startup.updateError": "Impossible de mettre à jour le réglage de restauration au démarrage.",
   "settings.section.notifications.title": "Notifications",
   "settings.section.notifications.subtitle": "Contrôlez les notifications système liées à l'activité des sessions.",
   "settings.notifications.permission.granted": "Accordée",
@@ -132,6 +179,18 @@ export const settingsMessages = {
   "settings.opencode.logLevel.option.info": "Info",
   "settings.opencode.logLevel.option.warn": "Avertissement",
   "settings.opencode.logLevel.option.error": "Erreur",
+  "settings.opencode.update.title": "Mises à jour OpenCode",
+  "settings.opencode.update.subtitle": "Vérifiez et installez les mises à jour du binaire OpenCode configuré.",
+  "settings.opencode.update.checking": "Recherche de mises à jour...",
+  "settings.opencode.update.checkFailed": "Impossible de rechercher les mises à jour OpenCode.",
+  "settings.opencode.update.retry": "Réessayer",
+  "settings.opencode.update.installed": "Version installée",
+  "settings.opencode.update.upToDate": "OpenCode est à jour.",
+  "settings.opencode.update.action": "Mettre à jour vers OpenCode {version}",
+  "settings.opencode.update.updating": "Mise à jour d’OpenCode...",
+  "settings.opencode.update.requiresInstance": "Démarrez un espace de travail avec ce binaire pour installer la mise à jour.",
+  "settings.opencode.update.success": "OpenCode {version} est installé. Les nouvelles instances utiliseront la version mise à jour.",
+  "settings.opencode.update.failed": "La mise à jour d’OpenCode a échoué. La version installée n’a pas été modifiée.",
   "settings.configFiles.title": "Fichiers de configuration",
   "settings.configFiles.subtitle": "Modifiez les fichiers de configuration globaux autorisés sur ce serveur.",
   "settings.configFiles.selector.label": "Fichier",
@@ -151,6 +210,7 @@ export const settingsMessages = {
   "settings.configFiles.confirmDiscard.cancelLabel": "Continuer la modification",
 
   "settings.providers.title": "Authentification des fournisseurs",
+  "settings.providers.target": "Instance OpenCode : {workspace}",
   "settings.providers.subtitle": "Connectez des clés API ou des comptes OAuth pour l'instance OpenCode active.",
   "settings.providers.refresh": "Actualiser",
   "settings.providers.selectProvider": "Sélectionner un fournisseur",
@@ -208,8 +268,8 @@ export const settingsMessages = {
   "settings.providers.errors.envDisconnectUnavailable": "Ce fournisseur est configuré depuis des variables d'environnement et ne peut pas être déconnecté depuis l'interface.",
 
   "settings.appearance.behavior.title": "Interaction",
-  "settings.appearance.behavior.subtitle": "Parametres par defaut pour les messages, les diffs et la saisie.",
-  "settings.behavior.expansionPresets.ariaLabel": "Transcript detail presets",
+  "settings.appearance.behavior.subtitle": "Controlez ensemble le niveau de detail des messages, outils, diagnostics et metriques.",
+  "settings.behavior.expansionPresets.ariaLabel": "Prereglages de detail de conversation",
   "settings.behavior.expansionPreset.minimal.title": "Minimal",
   "settings.behavior.expansionPreset.minimal.description": "Keep most generated detail tucked away until needed.",
   "settings.behavior.expansionPreset.balanced.title": "Balanced",
@@ -266,6 +326,7 @@ export const settingsMessages = {
   "settings.speech.status.loading": "Vérification de la configuration...",
   "settings.speech.status.configured": "Configuré",
   "settings.speech.status.missing": "Clé API manquante",
+  "settings.speech.status.partial": "Partiellement configuré",
   "settings.speech.status.error": "Service vocal indisponible",
   "settings.speech.apiKey.title": "Clé API",
   "settings.speech.apiKey.subtitle": "Utilisée pour les requêtes vocales gérées par CodeNomad.",
@@ -297,11 +358,44 @@ export const settingsMessages = {
   "settings.speech.testPlayback.stop": "Arreter l'extrait",
   "settings.speech.testPlayback.sample": "Merci d'utiliser CodeNomad, vos parametres vocaux fonctionnent correctement.",
   "settings.speech.testPlayback.note": "Le test utilise immediatement le mode et le format actuels. Enregistrez d'abord les changements d'API key, d'URL de base, de modele ou de voix si vous voulez aussi les tester.",
+  "settings.speech.testInput.action": "Tester l'entrée",
+  "settings.speech.testInput.stop": "Arrêter l'enregistrement",
+  "settings.speech.testInput.transcribing": "Transcription",
+  "settings.speech.testInput.requesting": "Démarrage…",
+  "settings.speech.testInput.empty": "Aucune parole détectée",
   "settings.speech.save.action": "Enregistrer",
   "settings.speech.save.saving": "Enregistrement...",
   "settings.speech.save.saved": "Enregistré",
   "settings.speech.save.unsaved": "Modifications non enregistrées",
   "settings.speech.save.error": "Échec de l'enregistrement",
+  "settings.speech.separateProviders.title": "Fournisseurs séparés pour l'entrée et la sortie",
+  "settings.speech.separateProviders.subtitle": "Utiliser différentes clés API et points de terminaison pour l'entrée vocale (STT) et la sortie (TTS).",
+  "settings.speech.stt.section.title": "Entrée vocale (Voix vers texte)",
+  "settings.speech.tts.section.title": "Sortie vocale (Texte vers voix)",
+  "settings.speech.stt.apiKey.title": "Clé API d'entrée",
+  "settings.speech.stt.apiKey.subtitle": "Utilisée pour les requêtes de voix vers texte.",
+  "settings.speech.stt.apiKey.placeholder": "Saisissez une nouvelle clé API d'entrée",
+  "settings.speech.stt.apiKey.storedNote": "Une clé API d'entrée enregistrée est masquée. Saisissez une nouvelle valeur pour la remplacer.",
+  "settings.speech.stt.apiKey.usingShared": "Utilise la clé API partagée. Saisissez une nouvelle clé pour remplacer.",
+  "settings.speech.stt.apiKey.clearAction": "Effacer la clé d'entrée enregistrée",
+  "settings.speech.stt.apiKey.clearPending": "La clé API d'entrée enregistrée sera supprimée lors de l'enregistrement.",
+  "settings.speech.stt.baseUrl.title": "URL de base d'entrée",
+  "settings.speech.stt.baseUrl.subtitle": "Point de terminaison compatible OpenAI pour la transcription.",
+  "settings.speech.stt.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.stt.model.title": "Modèle d'entrée",
+  "settings.speech.stt.model.subtitle": "Modèle utilisé pour la voix vers texte.",
+  "settings.speech.tts.apiKey.title": "Clé API de sortie",
+  "settings.speech.tts.apiKey.subtitle": "Utilisée pour les requêtes de texte vers voix.",
+  "settings.speech.tts.apiKey.placeholder": "Saisissez une nouvelle clé API de sortie",
+  "settings.speech.tts.apiKey.storedNote": "Une clé API de sortie enregistrée est masquée. Saisissez une nouvelle valeur pour la remplacer.",
+  "settings.speech.tts.apiKey.usingShared": "Utilise la clé API partagée. Saisissez une nouvelle clé pour remplacer.",
+  "settings.speech.tts.apiKey.clearAction": "Effacer la clé de sortie enregistrée",
+  "settings.speech.tts.apiKey.clearPending": "La clé API de sortie enregistrée sera supprimée lors de l'enregistrement.",
+  "settings.speech.tts.baseUrl.title": "URL de base de sortie",
+  "settings.speech.tts.baseUrl.subtitle": "Point de terminaison compatible OpenAI pour la synthèse.",
+  "settings.speech.tts.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.tts.model.title": "Modèle de sortie",
+  "settings.speech.tts.model.subtitle": "Modèle utilisé pour le texte vers voix.",
   "settings.nav.sidecars": "SideCars",
   "settings.section.sidecars.eyebrow": "Services serveur",
   "settings.section.sidecars.title": "SideCars",
diff --git a/packages/ui/src/lib/i18n/messages/he/commands.ts b/packages/ui/src/lib/i18n/messages/he/commands.ts
index 1969ebf4..a432e042 100644
--- a/packages/ui/src/lib/i18n/messages/he/commands.ts
+++ b/packages/ui/src/lib/i18n/messages/he/commands.ts
@@ -123,12 +123,12 @@ export const commandMessages = {
   "commands.diffViewUnified.keywords": "diff, מאוחד, תצוגה",
 
   "commands.toolOutputsDefault.label": "ברירת מחדל לפלטי כלים · {state}",
-  "commands.toolOutputsDefault.description": "החלף ברירת מחדל לפריסת פלטי כלים",
-  "commands.toolOutputsDefault.keywords": "כלי, פלט, פרוס, כווץ",
+  "commands.toolOutputsDefault.description": "הגדר נראות ברירת מחדל לפלטי כלים",
+  "commands.toolOutputsDefault.keywords": "כלי, פלט, הסתר, פרוס, כווץ",
 
   "commands.diagnosticsDefault.label": "ברירת מחדל לאבחון · {state}",
-  "commands.diagnosticsDefault.description": "החלף ברירת מחדל לפריסת פלט אבחון",
-  "commands.diagnosticsDefault.keywords": "אבחון, פרוס, כווץ",
+  "commands.diagnosticsDefault.description": "הגדר נראות ברירת מחדל לפלט אבחון",
+  "commands.diagnosticsDefault.keywords": "אבחון, הסתר, פרוס, כווץ",
 
   "commands.toolInputsVisibility.label": "נראות קלטי כלים · {state}",
   "commands.toolInputsVisibility.description": "הגדר נראות ברירת מחדל לארגומנטים של קריאות כלי",
diff --git a/packages/ui/src/lib/i18n/messages/he/folderSelection.ts b/packages/ui/src/lib/i18n/messages/he/folderSelection.ts
index e317ffe0..26f8dc4b 100644
--- a/packages/ui/src/lib/i18n/messages/he/folderSelection.ts
+++ b/packages/ui/src/lib/i18n/messages/he/folderSelection.ts
@@ -17,10 +17,8 @@ export const folderSelectionMessages = {
   "folderSelection.recent.rename": "שנה שם סביבת עבודה",
   "folderSelection.recent.remove": "הסר מהרשימה האחרונה",
   "folderSelection.recent.openBadge": "פתוח",
-  "folderSelection.recent.alreadyOpenTitle": "הפרויקט כבר פתוח",
-  "folderSelection.recent.alreadyOpenMessage": "בחר כיצד לפתוח את התיקייה הזו.",
+  "folderSelection.recent.openNewInstance": "פתיחת מופע חדש",
   "folderSelection.recent.switchToOpenProject": "עבור לפרויקט הפתוח",
-  "folderSelection.recent.openAnotherInstance": "פתח מופע נוסף",
 
   "folderSelection.browse.title": "עיון בתיקייה",
   "folderSelection.browse.subtitle": "בחר כל תיקייה במחשב שלך",
diff --git a/packages/ui/src/lib/i18n/messages/he/instance.ts b/packages/ui/src/lib/i18n/messages/he/instance.ts
index 0cecf156..4d5a4af4 100644
--- a/packages/ui/src/lib/i18n/messages/he/instance.ts
+++ b/packages/ui/src/lib/i18n/messages/he/instance.ts
@@ -93,6 +93,19 @@ export const instanceMessages = {
   "instanceShell.rightPanel.tabs.files": "קבצים",
   "instanceShell.rightPanel.tabs.status": "סטטוס",
   "instanceShell.rightPanel.tabs.ariaLabel": "לשוניות לוח ימני",
+  "instanceShell.rightPanel.customize.toggle": "התאמת הלוח הימני",
+  "instanceShell.rightPanel.customize.title": "התאמת הלוח הימני",
+  "instanceShell.rightPanel.customize.description": "הצגה או הסתרה של כרטיסיות ומקטעי סטטוס.",
+  "instanceShell.rightPanel.customize.reset": "איפוס",
+  "instanceShell.rightPanel.customize.tabs": "כרטיסיות",
+  "instanceShell.rightPanel.customize.statusSections": "מקטעי סטטוס",
+  "instanceShell.rightPanel.customize.dragToReorder": "גררו כרטיסיות או מקטעי סטטוס כדי לסדר מחדש.",
+  "instanceShell.rightPanel.customize.moveUp": "למעלה",
+  "instanceShell.rightPanel.customize.moveDown": "למטה",
+  "instanceShell.rightPanel.customize.moveTabUp": "העברת הכרטיסייה {label} למעלה",
+  "instanceShell.rightPanel.customize.moveTabDown": "העברת הכרטיסייה {label} למטה",
+  "instanceShell.rightPanel.customize.moveStatusSectionUp": "העברת מקטע הסטטוס {label} למעלה",
+  "instanceShell.rightPanel.customize.moveStatusSectionDown": "העברת מקטע הסטטוס {label} למטה",
   "instanceShell.rightPanel.actions.refresh": "רענן",
   "instanceShell.rightPanel.actions.save": "שמור (Ctrl+S)",
   "instanceShell.rightPanel.actions.saveConfirm.message": "האם ברצונך לשמור את השינויים ב-\"{path}\" לפני המעבר?",
@@ -191,7 +204,7 @@ export const instanceMessages = {
 
   "instanceShell.yoloMode.noSessionSelected": "בחרו סשן כדי להגדיר מצב Yolo.",
   "instanceShell.yoloMode.title": "מצב Yolo",
-  "instanceShell.yoloMode.description": "מאשר אוטומטית בקשות הרשאה עבור הסשן הזה. כבוי כברירת מחדל.",
+  "instanceShell.yoloMode.description": "מאשר אוטומטית בקשות הרשאה עבור הסשן הזה.",
   "instanceShell.yoloMode.badge": "Yolo",
   "instanceShell.yoloMode.badgeAriaLabel": "מצב Yolo פעיל",
 
diff --git a/packages/ui/src/lib/i18n/messages/he/markdown.ts b/packages/ui/src/lib/i18n/messages/he/markdown.ts
index 5505c65b..bfa23682 100644
--- a/packages/ui/src/lib/i18n/messages/he/markdown.ts
+++ b/packages/ui/src/lib/i18n/messages/he/markdown.ts
@@ -2,6 +2,8 @@ export const markdownMessages = {
   "markdown.codeBlock.copy.label": "העתק",
   "markdown.codeBlock.copy.copied": "הועתק!",
   "markdown.codeBlock.copy.failed": "נכשל",
+  "markdown.codeBlock.wrap.enable": "הפעל גלישת שורות",
+  "markdown.codeBlock.wrap.disable": "כבה גלישת שורות",
 
   "markdown.copy": "העתק",
 } as const
diff --git a/packages/ui/src/lib/i18n/messages/he/messaging.ts b/packages/ui/src/lib/i18n/messages/he/messaging.ts
index e7ce0505..a342b71e 100644
--- a/packages/ui/src/lib/i18n/messages/he/messaging.ts
+++ b/packages/ui/src/lib/i18n/messages/he/messaging.ts
@@ -17,6 +17,7 @@ export const messagingMessages = {
   "messageSection.empty.tips.attachFilesPrefix": "צרף קבצים עם",
   "messageSection.loading.messages": "טוען הודעות...",
   "messageSection.loadError.title": "לא ניתן לטעון הודעות",
+  "messageSection.loadError.detail": "OpenCode לא החזיר את הודעות הסשן.",
   "messageSection.loadError.reload": "טען הודעות מחדש",
   "messageSection.scroll.toFirstAriaLabel": "גלול להודעה הראשונה",
   "messageSection.scroll.toLatestAriaLabel": "גלול להודעה האחרונה",
@@ -71,6 +72,8 @@ export const messagingMessages = {
   "messageBlock.usage.cacheRead": "קריאת מטמון",
   "messageBlock.usage.cacheWrite": "כתיבת מטמון",
   "messageBlock.usage.cost": "עלות",
+  "messageBlock.usage.expandAriaLabel": "הרחבת מדדי טוקנים",
+  "messageBlock.usage.collapseAriaLabel": "כיווץ מדדי טוקנים",
   "messageBlock.step.agentLabel": "סוכן: {agent}",
   "messageBlock.step.modelLabel": "מודל: {model}",
   "messageBlock.reasoning.thinkingLabel": "חשיבה",
diff --git a/packages/ui/src/lib/i18n/messages/he/session.ts b/packages/ui/src/lib/i18n/messages/he/session.ts
index 55ba4a79..59044fab 100644
--- a/packages/ui/src/lib/i18n/messages/he/session.ts
+++ b/packages/ui/src/lib/i18n/messages/he/session.ts
@@ -15,6 +15,7 @@ export const sessionMessages = {
   "sessionList.status.working": "עובד",
   "sessionList.status.compacting": "מסכם",
   "sessionList.status.idle": "מוכן",
+  "sessionList.status.interrupted": "הופסק",
   "sessionList.status.retrying": "מנסה שוב",
   "sessionList.status.retryingIn": "מנסה שוב בעוד {seconds}ש׳",
   "sessionList.status.retryTooltip": "{message} (ניסיון {attempt})",
@@ -48,6 +49,10 @@ export const sessionMessages = {
   "sessionList.filter.placeholder": "חפש סשנים…",
   "sessionList.filter.ariaLabel": "חפש סשנים",
   "sessionList.loading.more": "טוען עוד סשנים…",
+  "sessionList.loading.initial": "טוען סשנים…",
+  "sessionList.loadError.title": "לא ניתן לטעון את הסשנים",
+  "sessionList.loadError.detail": "OpenCode לא החזיר את רשימת הסשנים.",
+  "sessionList.loadError.retry": "נסה שוב",
   "sessionList.selection.selectAllLabel": "בחר הכל",
   "sessionList.selection.selectAllAriaLabel": "בחר את כל הסשנים",
   "sessionList.selection.clearLabel": "נקה",
diff --git a/packages/ui/src/lib/i18n/messages/he/settings.ts b/packages/ui/src/lib/i18n/messages/he/settings.ts
index d5f61bb7..a7f9c7fb 100644
--- a/packages/ui/src/lib/i18n/messages/he/settings.ts
+++ b/packages/ui/src/lib/i18n/messages/he/settings.ts
@@ -56,6 +56,7 @@ export const settingsMessages = {
   "contextUsagePanel.labels.input": "קלט",
   "contextUsagePanel.labels.output": "פלט",
   "contextUsagePanel.labels.cost": "עלות",
+  "contextUsagePanel.included": "כלול",
   "contextUsagePanel.labels.totalInput": "קלט כולל",
   "contextUsagePanel.labels.totalOutput": "פלט כולל",
   "contextUsagePanel.labels.totalCost": "עלות כוללת",
@@ -64,6 +65,32 @@ export const settingsMessages = {
   "contextUsagePanel.labels.available": "זמין",
   "contextUsagePanel.unavailable": "--",
 
+  "providerUsage.title": "שימוש",
+  "providerUsage.tooltip": "שימוש וחלונות איפוס עבור הספק שנבחר בהפעלה הפעילה.",
+  "providerUsage.noSession": "יש לבחור הפעלה כדי להציג את השימוש בתוכנית.",
+  "providerUsage.loading": "טוען נתוני שימוש...",
+  "providerUsage.unsupported": "נתוני שימוש אינם זמינים לספק זה.",
+  "providerUsage.notConfigured": "לא נמצאו פרטי מנוי תואמים.",
+  "providerUsage.unavailable": "נתוני השימוש אינם זמינים כרגע.",
+  "providerUsage.unavailableValue": "--",
+  "providerUsage.usedPercent": "{percent}% בשימוש",
+  "providerUsage.resets": "איפוס {time}",
+  "providerUsage.progressLabel": "שימוש בתוכנית {window}",
+  "providerUsage.windows.fiveHours": "5 שעות",
+  "providerUsage.windows.sevenDays": "7 ימים",
+  "providerUsage.windows.sevenDaysSonnet": "7 ימים · Sonnet",
+  "providerUsage.windows.sevenDaysOpus": "7 ימים · Opus",
+  "providerUsage.windows.weekly": "שבועי",
+  "providerUsage.windows.daily": "יומי",
+  "providerUsage.windows.monthly": "חודשי",
+  "providerUsage.windows.credits": "זיכויים",
+  "providerUsage.windows.billingCycle": "מחזור חיוב",
+  "providerUsage.windows.session": "הפעלה",
+  "providerUsage.windows.premium": "בקשות פרימיום",
+  "providerUsage.windows.chat": "צ׳אט",
+  "providerUsage.windows.completions": "השלמות",
+  "providerUsage.windows.mcpTools": "כלי MCP",
+
   "settings.title": "הגדרות",
   "settings.navigationAriaLabel": "קטגוריות הגדרות",
   "settings.close": "סגור הגדרות",
@@ -71,6 +98,16 @@ export const settingsMessages = {
   "settings.open.title": "פתח הגדרות",
   "settings.open.ariaLabel": "פתח הגדרות",
   "settings.nav.appearance": "מראה",
+  "settings.nav.general": "כללי",
+  "settings.nav.chat": "צ׳אט",
+  "settings.nav.voice": "קול",
+  "settings.nav.connections": "חיבורים",
+  "settings.nav.runtime": "זמן ריצה",
+  "settings.nav.advanced": "מתקדם",
+  "settings.nav.about": "אודות",
+  "settings.general.language.subtitle": "בחר את השפה שתשמש בכל היישום.",
+  "settings.behavior.holdLongAssistantReplies.title": "השהיית מעקב אחר תשובות ארוכות",
+  "settings.behavior.holdLongAssistantReplies.subtitle": "הפסק מעקב אוטומטי כאשר תשובה זורמת חורגת מחלון התצוגה.",
   "settings.nav.notifications": "התראות",
   "settings.nav.remote": "גישה מרוחקת",
   "settings.nav.speech": "קול",
@@ -89,6 +126,16 @@ export const settingsMessages = {
   "settings.appearance.theme.option.system": "התאם להגדרת מערכת ההפעלה",
   "settings.appearance.theme.option.light": "השתמש במראה בהיר",
   "settings.appearance.theme.option.dark": "השתמש במראה כהה",
+  "settings.appearance.startup.title": "הפעלה",
+  "settings.appearance.startup.subtitle": "בחר מה ישוחזר במכשיר זה בעת הפעלת CodeNomad.",
+  "settings.appearance.startup.restore.title": "שחזור המצב הקודם",
+  "settings.appearance.startup.restore.subtitle": "פתיחה מחדש של כרטיסיות סביבות עבודה ו-sidecar, הפעלות פעילות והודעות שלא נשלחו, ושחזור מיקומי גלילה, פריסת חלוניות, מיקום החלון ורמת התקריב.",
+  "settings.appearance.startup.clear.title": "מצב הפעלה שמור",
+  "settings.appearance.startup.clear.subtitle": "הסרת כרטיסיות, טיוטות, מיקומי גלילה ופריסת חלוניות שנשמרו. נתוני CodeNomad ו-OpenCode לא יימחקו.",
+  "settings.appearance.startup.clear.action": "נקה מצב שמור",
+  "settings.appearance.startup.clearSuccess": "מצב ההפעלה השמור נוקה.",
+  "settings.appearance.startup.clearError": "לא ניתן לנקות את מצב ההפעלה השמור.",
+  "settings.appearance.startup.updateError": "לא ניתן לעדכן את הגדרת השחזור בעת הפעלה.",
   "settings.section.notifications.title": "התראות",
   "settings.section.notifications.subtitle": "שלוט בהתראות ברמת מערכת ההפעלה עבור פעילות סשן.",
   "settings.notifications.permission.granted": "ניתן",
@@ -132,6 +179,18 @@ export const settingsMessages = {
   "settings.opencode.logLevel.option.info": "מידע",
   "settings.opencode.logLevel.option.warn": "אזהרה",
   "settings.opencode.logLevel.option.error": "שגיאה",
+  "settings.opencode.update.title": "עדכוני OpenCode",
+  "settings.opencode.update.subtitle": "בדיקה והתקנה של עדכונים לקובץ OpenCode שהוגדר.",
+  "settings.opencode.update.checking": "בודק עדכונים...",
+  "settings.opencode.update.checkFailed": "לא ניתן לבדוק עדכוני OpenCode.",
+  "settings.opencode.update.retry": "נסה שוב",
+  "settings.opencode.update.installed": "גרסה מותקנת",
+  "settings.opencode.update.upToDate": "OpenCode מעודכן.",
+  "settings.opencode.update.action": "עדכון ל-OpenCode {version}",
+  "settings.opencode.update.updating": "מעדכן את OpenCode...",
+  "settings.opencode.update.requiresInstance": "יש להפעיל סביבת עבודה עם קובץ זה כדי להתקין את העדכון.",
+  "settings.opencode.update.success": "OpenCode {version} הותקן. מופעים חדשים ישתמשו בגרסה המעודכנת.",
+  "settings.opencode.update.failed": "עדכון OpenCode נכשל. הגרסה המותקנת לא השתנתה.",
   "settings.configFiles.title": "קובצי הגדרות",
   "settings.configFiles.subtitle": "ערוך קובצי הגדרות גלובליים שנמצאים ברשימת ההרשאות בשרת הזה.",
   "settings.configFiles.selector.label": "קובץ",
@@ -151,6 +210,7 @@ export const settingsMessages = {
   "settings.configFiles.confirmDiscard.cancelLabel": "המשך לערוך",
 
   "settings.providers.title": "אימות ספקים",
+  "settings.providers.target": "מופע OpenCode: {workspace}",
   "settings.providers.subtitle": "חבר מפתחות API או חשבונות OAuth עבור מופע OpenCode הפעיל.",
   "settings.providers.refresh": "רענן",
   "settings.providers.selectProvider": "בחר ספק",
@@ -208,8 +268,8 @@ export const settingsMessages = {
   "settings.providers.errors.envDisconnectUnavailable": "ספק זה מוגדר ממשתני סביבה ולא ניתן לנתק אותו מהממשק.",
 
   "settings.appearance.behavior.title": "אינטראקציה",
-  "settings.appearance.behavior.subtitle": "ברירות מחדל להודעות, diff וקלט.",
-  "settings.behavior.expansionPresets.ariaLabel": "Transcript detail presets",
+  "settings.appearance.behavior.subtitle": "שליטה משותפת ברמת הפירוט של הודעות, כלים, אבחון ושימוש.",
+  "settings.behavior.expansionPresets.ariaLabel": "הגדרות קבועות מראש לפירוט השיחה",
   "settings.behavior.expansionPreset.minimal.title": "Minimal",
   "settings.behavior.expansionPreset.minimal.description": "Keep most generated detail tucked away until needed.",
   "settings.behavior.expansionPreset.balanced.title": "Balanced",
@@ -266,6 +326,7 @@ export const settingsMessages = {
   "settings.speech.status.loading": "בודק את ההגדרות...",
   "settings.speech.status.configured": "מוגדר",
   "settings.speech.status.missing": "חסר מפתח API",
+  "settings.speech.status.partial": "מוגדר חלקית",
   "settings.speech.status.error": "שירות הקול אינו זמין",
   "settings.speech.apiKey.title": "מפתח API",
   "settings.speech.apiKey.subtitle": "משמש עבור בקשות קול המנוהלות על ידי CodeNomad.",
@@ -297,11 +358,44 @@ export const settingsMessages = {
   "settings.speech.testPlayback.stop": "עצור דוגמה",
   "settings.speech.testPlayback.sample": "תודה שאתה משתמש ב-CodeNomad, הגדרות הקול שלך פועלות כראוי.",
   "settings.speech.testPlayback.note": "המבחן משתמש מיד במצב ובפורמט הנוכחיים. שמור תחילה שינויים ב-API key, ב-Base URL, במודל או בקול אם גם אותם תרצה לבדוק.",
+  "settings.speech.testInput.action": "בדיקת קלט",
+  "settings.speech.testInput.stop": "עצור הקלטה",
+  "settings.speech.testInput.transcribing": "מתמלל",
+  "settings.speech.testInput.requesting": "מתחיל…",
+  "settings.speech.testInput.empty": "לא זוהתה דיבור",
   "settings.speech.save.action": "שמור",
   "settings.speech.save.saving": "שומר...",
   "settings.speech.save.saved": "נשמר",
   "settings.speech.save.unsaved": "יש שינויים שלא נשמרו",
   "settings.speech.save.error": "השמירה נכשלה",
+  "settings.speech.separateProviders.title": "ספקים נפרדים לקלט ולפלט",
+  "settings.speech.separateProviders.subtitle": "שימוש במפתחות API ונקודות קצה שונים לקלט קולי (STT) ולפלט (TTS).",
+  "settings.speech.stt.section.title": "קלט קולי (דיבור לטקסט)",
+  "settings.speech.tts.section.title": "פלט קולי (טקסט לדיבור)",
+  "settings.speech.stt.apiKey.title": "מפתח API לקלט",
+  "settings.speech.stt.apiKey.subtitle": "משמש עבור בקשות דיבור לטקסט.",
+  "settings.speech.stt.apiKey.placeholder": "הזן מפתח API חדש לקלט",
+  "settings.speech.stt.apiKey.storedNote": "מפתח API קלט שמור מוסתר. הזן ערך חדש כדי להחליף אותו.",
+  "settings.speech.stt.apiKey.usingShared": "משתמש במפתח API המשותף. הזן מפתח חדש כדי להחליף.",
+  "settings.speech.stt.apiKey.clearAction": "נקה מפתח קלט שמור",
+  "settings.speech.stt.apiKey.clearPending": "מפתח ה-API לקלט השמור יוסר בעת השמירה.",
+  "settings.speech.stt.baseUrl.title": "כתובת בסיס לקלט",
+  "settings.speech.stt.baseUrl.subtitle": "נקודת קצה תואמת OpenAI לתמלול.",
+  "settings.speech.stt.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.stt.model.title": "מודל קלט",
+  "settings.speech.stt.model.subtitle": "מודל המשמש לדיבור לטקסט.",
+  "settings.speech.tts.apiKey.title": "מפתח API לפלט",
+  "settings.speech.tts.apiKey.subtitle": "משמש עבור בקשות טקסט לדיבור.",
+  "settings.speech.tts.apiKey.placeholder": "הזן מפתח API חדש לפלט",
+  "settings.speech.tts.apiKey.storedNote": "מפתח API פלט שמור מוסתר. הזן ערך חדש כדי להחליף אותו.",
+  "settings.speech.tts.apiKey.usingShared": "משתמש במפתח API המשותף. הזן מפתח חדש כדי להחליף.",
+  "settings.speech.tts.apiKey.clearAction": "נקה מפתח פלט שמור",
+  "settings.speech.tts.apiKey.clearPending": "מפתח ה-API לפלט השמור יוסר בעת השמירה.",
+  "settings.speech.tts.baseUrl.title": "כתובת בסיס לפלט",
+  "settings.speech.tts.baseUrl.subtitle": "נקודת קצה תואמת OpenAI לסינתזה.",
+  "settings.speech.tts.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.tts.model.title": "מודל פלט",
+  "settings.speech.tts.model.subtitle": "מודל המשמש לטקסט לדיבור.",
   "settings.nav.sidecars": "SideCars",
   "settings.section.sidecars.eyebrow": "שירותי שרת",
   "settings.section.sidecars.title": "SideCars",
diff --git a/packages/ui/src/lib/i18n/messages/ja/commands.ts b/packages/ui/src/lib/i18n/messages/ja/commands.ts
index 78ddd61d..c00b13d4 100644
--- a/packages/ui/src/lib/i18n/messages/ja/commands.ts
+++ b/packages/ui/src/lib/i18n/messages/ja/commands.ts
@@ -123,12 +123,12 @@ export const commandMessages = {
   "commands.diffViewUnified.keywords": "diff, ユニファイド, 表示, unified, view",
 
   "commands.toolOutputsDefault.label": "ツール出力の既定 · {state}",
-  "commands.toolOutputsDefault.description": "ツール出力を既定で展開するか切り替え",
-  "commands.toolOutputsDefault.keywords": "ツール, 出力, 展開, 折りたたみ, tool, output, expand, collapse",
+  "commands.toolOutputsDefault.description": "ツール出力の既定の表示状態を設定",
+  "commands.toolOutputsDefault.keywords": "ツール, 出力, 非表示, 展開, 折りたたみ, tool, output, hide, expand, collapse",
 
   "commands.diagnosticsDefault.label": "診断の既定 · {state}",
-  "commands.diagnosticsDefault.description": "診断出力を既定で展開するか切り替え",
-  "commands.diagnosticsDefault.keywords": "診断, 展開, 折りたたみ, diagnostics, expand, collapse",
+  "commands.diagnosticsDefault.description": "診断出力の既定の表示状態を設定",
+  "commands.diagnosticsDefault.keywords": "診断, 非表示, 展開, 折りたたみ, diagnostics, hide, expand, collapse",
 
   "commands.toolInputsVisibility.label": "ツール入力の表示 · {state}",
   "commands.toolInputsVisibility.description": "ツール呼び出しの入力引数の既定の表示状態を設定します",
diff --git a/packages/ui/src/lib/i18n/messages/ja/folderSelection.ts b/packages/ui/src/lib/i18n/messages/ja/folderSelection.ts
index 0cf6b4ea..23052865 100644
--- a/packages/ui/src/lib/i18n/messages/ja/folderSelection.ts
+++ b/packages/ui/src/lib/i18n/messages/ja/folderSelection.ts
@@ -17,10 +17,8 @@ export const folderSelectionMessages = {
   "folderSelection.recent.rename": "ワークスペース名を変更",
   "folderSelection.recent.remove": "履歴から削除",
   "folderSelection.recent.openBadge": "開いています",
-  "folderSelection.recent.alreadyOpenTitle": "プロジェクトはすでに開いています",
-  "folderSelection.recent.alreadyOpenMessage": "このフォルダの開き方を選択してください。",
+  "folderSelection.recent.openNewInstance": "新しいインスタンスを開く",
   "folderSelection.recent.switchToOpenProject": "開いているプロジェクトに切り替え",
-  "folderSelection.recent.openAnotherInstance": "別のインスタンスを開く",
 
   "folderSelection.browse.title": "フォルダを参照",
   "folderSelection.browse.subtitle": "コンピュータ上の任意のフォルダを選択",
diff --git a/packages/ui/src/lib/i18n/messages/ja/instance.ts b/packages/ui/src/lib/i18n/messages/ja/instance.ts
index e61796d5..b4eb2225 100644
--- a/packages/ui/src/lib/i18n/messages/ja/instance.ts
+++ b/packages/ui/src/lib/i18n/messages/ja/instance.ts
@@ -93,6 +93,19 @@ export const instanceMessages = {
   "instanceShell.rightPanel.tabs.files": "ファイル",
   "instanceShell.rightPanel.tabs.status": "ステータス",
   "instanceShell.rightPanel.tabs.ariaLabel": "右パネルのタブ",
+  "instanceShell.rightPanel.customize.toggle": "右パネルをカスタマイズ",
+  "instanceShell.rightPanel.customize.title": "右パネルをカスタマイズ",
+  "instanceShell.rightPanel.customize.description": "タブとステータスセクションの表示/非表示を切り替えます。",
+  "instanceShell.rightPanel.customize.reset": "リセット",
+  "instanceShell.rightPanel.customize.tabs": "タブ",
+  "instanceShell.rightPanel.customize.statusSections": "ステータスセクション",
+  "instanceShell.rightPanel.customize.dragToReorder": "タブまたはステータスセクションをドラッグして並べ替えます。",
+  "instanceShell.rightPanel.customize.moveUp": "上へ",
+  "instanceShell.rightPanel.customize.moveDown": "下へ",
+  "instanceShell.rightPanel.customize.moveTabUp": "{label} タブを上へ移動",
+  "instanceShell.rightPanel.customize.moveTabDown": "{label} タブを下へ移動",
+  "instanceShell.rightPanel.customize.moveStatusSectionUp": "{label} ステータスセクションを上へ移動",
+  "instanceShell.rightPanel.customize.moveStatusSectionDown": "{label} ステータスセクションを下へ移動",
   "instanceShell.rightPanel.actions.refresh": "更新",
   "instanceShell.rightPanel.actions.save": "保存 (Ctrl+S)",
   "instanceShell.rightPanel.actions.saveConfirm.message": "「{path}」への変更を切り替え前に保存しますか？",
@@ -167,7 +180,7 @@ export const instanceMessages = {
 
   "instanceShell.yoloMode.noSessionSelected": "Yoloモードを設定するにはセッションを選択してください。",
   "instanceShell.yoloMode.title": "Yoloモード",
-  "instanceShell.yoloMode.description": "このセッションの権限リクエストを自動承認します。デフォルトでは無効です。",
+  "instanceShell.yoloMode.description": "このセッションの権限リクエストを自動承認します。",
   "instanceShell.yoloMode.badge": "Yolo",
   "instanceShell.yoloMode.badgeAriaLabel": "Yoloモードが有効",
 
diff --git a/packages/ui/src/lib/i18n/messages/ja/markdown.ts b/packages/ui/src/lib/i18n/messages/ja/markdown.ts
index 786f471c..e8f1cfaf 100644
--- a/packages/ui/src/lib/i18n/messages/ja/markdown.ts
+++ b/packages/ui/src/lib/i18n/messages/ja/markdown.ts
@@ -2,6 +2,8 @@ export const markdownMessages = {
   "markdown.codeBlock.copy.label": "コピー",
   "markdown.codeBlock.copy.copied": "コピーしました!",
   "markdown.codeBlock.copy.failed": "失敗",
+  "markdown.codeBlock.wrap.enable": "折り返しを有効にする",
+  "markdown.codeBlock.wrap.disable": "折り返しを無効にする",
 
   "markdown.copy": "コピー",
 } as const
diff --git a/packages/ui/src/lib/i18n/messages/ja/messaging.ts b/packages/ui/src/lib/i18n/messages/ja/messaging.ts
index ce2322c7..587ddc17 100644
--- a/packages/ui/src/lib/i18n/messages/ja/messaging.ts
+++ b/packages/ui/src/lib/i18n/messages/ja/messaging.ts
@@ -17,6 +17,7 @@ export const messagingMessages = {
   "messageSection.empty.tips.attachFilesPrefix": "次でファイルを添付:",
   "messageSection.loading.messages": "メッセージを読み込み中...",
   "messageSection.loadError.title": "メッセージを読み込めませんでした",
+  "messageSection.loadError.detail": "OpenCode からセッションメッセージが返されませんでした。",
   "messageSection.loadError.reload": "メッセージを再読み込み",
   "messageSection.scroll.toFirstAriaLabel": "最初のメッセージへスクロール",
   "messageSection.scroll.toLatestAriaLabel": "最新のメッセージへスクロール",
@@ -73,6 +74,8 @@ export const messagingMessages = {
   "messageBlock.usage.cacheRead": "キャッシュ読み込み",
   "messageBlock.usage.cacheWrite": "キャッシュ書き込み",
   "messageBlock.usage.cost": "コスト",
+  "messageBlock.usage.expandAriaLabel": "トークン使用量を展開",
+  "messageBlock.usage.collapseAriaLabel": "トークン使用量を折りたたむ",
   "messageBlock.step.agentLabel": "エージェント: {agent}",
   "messageBlock.step.modelLabel": "モデル: {model}",
   "messageBlock.reasoning.thinkingLabel": "思考",
diff --git a/packages/ui/src/lib/i18n/messages/ja/session.ts b/packages/ui/src/lib/i18n/messages/ja/session.ts
index 64fe690d..36855e8a 100644
--- a/packages/ui/src/lib/i18n/messages/ja/session.ts
+++ b/packages/ui/src/lib/i18n/messages/ja/session.ts
@@ -15,6 +15,7 @@ export const sessionMessages = {
   "sessionList.status.working": "作業中",
   "sessionList.status.compacting": "圧縮中",
   "sessionList.status.idle": "待機中",
+  "sessionList.status.interrupted": "中断",
   "sessionList.status.retrying": "再試行中",
   "sessionList.status.retryingIn": "{seconds}秒後に再試行",
   "sessionList.status.retryTooltip": "{message}（{attempt}回目）",
@@ -48,6 +49,10 @@ export const sessionMessages = {
   "sessionList.filter.placeholder": "セッションを検索…",
   "sessionList.filter.ariaLabel": "セッションを検索",
   "sessionList.loading.more": "セッションをさらに読み込んでいます…",
+  "sessionList.loading.initial": "セッションを読み込んでいます…",
+  "sessionList.loadError.title": "セッションを読み込めません",
+  "sessionList.loadError.detail": "OpenCode からセッション一覧が返されませんでした。",
+  "sessionList.loadError.retry": "再試行",
   "sessionList.selection.selectAllLabel": "すべて選択",
   "sessionList.selection.selectAllAriaLabel": "すべてのセッションを選択",
   "sessionList.selection.clearLabel": "クリア",
diff --git a/packages/ui/src/lib/i18n/messages/ja/settings.ts b/packages/ui/src/lib/i18n/messages/ja/settings.ts
index 1bf5ae7b..6b266a10 100644
--- a/packages/ui/src/lib/i18n/messages/ja/settings.ts
+++ b/packages/ui/src/lib/i18n/messages/ja/settings.ts
@@ -56,6 +56,7 @@ export const settingsMessages = {
   "contextUsagePanel.labels.input": "入力",
   "contextUsagePanel.labels.output": "出力",
   "contextUsagePanel.labels.cost": "コスト",
+  "contextUsagePanel.included": "含まれる",
   "contextUsagePanel.labels.totalInput": "合計入力",
   "contextUsagePanel.labels.totalOutput": "合計出力",
   "contextUsagePanel.labels.totalCost": "合計コスト",
@@ -64,6 +65,32 @@ export const settingsMessages = {
   "contextUsagePanel.labels.available": "残り",
   "contextUsagePanel.unavailable": "--",
 
+  "providerUsage.title": "使用量",
+  "providerUsage.tooltip": "アクティブなセッションで選択されたプロバイダーの使用量とリセット期間です。",
+  "providerUsage.noSession": "プラン使用量を表示するセッションを選択してください。",
+  "providerUsage.loading": "使用量を読み込み中...",
+  "providerUsage.unsupported": "このプロバイダーの使用量は利用できません。",
+  "providerUsage.notConfigured": "対応するサブスクリプション認証情報が見つかりません。",
+  "providerUsage.unavailable": "使用量は一時的に利用できません。",
+  "providerUsage.unavailableValue": "--",
+  "providerUsage.usedPercent": "{percent}% 使用",
+  "providerUsage.resets": "リセット {time}",
+  "providerUsage.progressLabel": "{window} のプラン使用量",
+  "providerUsage.windows.fiveHours": "5時間",
+  "providerUsage.windows.sevenDays": "7日間",
+  "providerUsage.windows.sevenDaysSonnet": "7日間 · Sonnet",
+  "providerUsage.windows.sevenDaysOpus": "7日間 · Opus",
+  "providerUsage.windows.weekly": "週間",
+  "providerUsage.windows.daily": "日次",
+  "providerUsage.windows.monthly": "月間",
+  "providerUsage.windows.credits": "クレジット",
+  "providerUsage.windows.billingCycle": "請求期間",
+  "providerUsage.windows.session": "セッション",
+  "providerUsage.windows.premium": "プレミアムリクエスト",
+  "providerUsage.windows.chat": "チャット",
+  "providerUsage.windows.completions": "補完",
+  "providerUsage.windows.mcpTools": "MCPツール",
+
   "settings.title": "設定",
   "settings.navigationAriaLabel": "設定セクション",
   "settings.close": "設定を閉じる",
@@ -71,6 +98,16 @@ export const settingsMessages = {
   "settings.open.title": "設定を開く",
   "settings.open.ariaLabel": "設定を開く",
   "settings.nav.appearance": "外観",
+  "settings.nav.general": "一般",
+  "settings.nav.chat": "チャット",
+  "settings.nav.voice": "音声",
+  "settings.nav.connections": "接続",
+  "settings.nav.runtime": "ランタイム",
+  "settings.nav.advanced": "詳細設定",
+  "settings.nav.about": "情報",
+  "settings.general.language.subtitle": "アプリケーション全体で使用する言語を選択します。",
+  "settings.behavior.holdLongAssistantReplies.title": "長いアシスタント応答を保持",
+  "settings.behavior.holdLongAssistantReplies.subtitle": "ストリーミング応答が画面を超えたときに自動追従を停止します。",
   "settings.nav.notifications": "通知",
   "settings.nav.remote": "リモートアクセス",
   "settings.nav.speech": "音声",
@@ -89,6 +126,16 @@ export const settingsMessages = {
   "settings.appearance.theme.option.system": "OS の設定に合わせる",
   "settings.appearance.theme.option.light": "ライト表示を使用",
   "settings.appearance.theme.option.dark": "ダーク表示を使用",
+  "settings.appearance.startup.title": "起動",
+  "settings.appearance.startup.subtitle": "CodeNomad の起動時にこのデバイスで復元する内容を選択します。",
+  "settings.appearance.startup.restore.title": "前回の状態を復元",
+  "settings.appearance.startup.restore.subtitle": "ワークスペースとサイドカーのタブ、アクティブなセッション、未送信メッセージを再度開き、スクロール位置、パネル配置、ウィンドウ位置、ズームを復元します。",
+  "settings.appearance.startup.clear.title": "保存された起動状態",
+  "settings.appearance.startup.clear.subtitle": "保存されたタブ、下書き、スクロール位置、パネル配置を削除します。CodeNomad と OpenCode のデータは削除されません。",
+  "settings.appearance.startup.clear.action": "保存状態を消去",
+  "settings.appearance.startup.clearSuccess": "保存された起動状態を消去しました。",
+  "settings.appearance.startup.clearError": "保存された起動状態を消去できませんでした。",
+  "settings.appearance.startup.updateError": "起動時の復元設定を更新できませんでした。",
   "settings.section.notifications.title": "通知",
   "settings.section.notifications.subtitle": "セッションの動作に関する OS レベルの通知を制御します。",
   "settings.notifications.permission.granted": "許可済み",
@@ -132,6 +179,18 @@ export const settingsMessages = {
   "settings.opencode.logLevel.option.info": "情報",
   "settings.opencode.logLevel.option.warn": "警告",
   "settings.opencode.logLevel.option.error": "エラー",
+  "settings.opencode.update.title": "OpenCode の更新",
+  "settings.opencode.update.subtitle": "設定された OpenCode バイナリの更新を確認してインストールします。",
+  "settings.opencode.update.checking": "更新を確認しています...",
+  "settings.opencode.update.checkFailed": "OpenCode の更新を確認できませんでした。",
+  "settings.opencode.update.retry": "再試行",
+  "settings.opencode.update.installed": "インストール済みバージョン",
+  "settings.opencode.update.upToDate": "OpenCode は最新です。",
+  "settings.opencode.update.action": "OpenCode {version} に更新",
+  "settings.opencode.update.updating": "OpenCode を更新しています...",
+  "settings.opencode.update.requiresInstance": "更新をインストールするには、このバイナリでワークスペースを起動してください。",
+  "settings.opencode.update.success": "OpenCode {version} がインストールされました。新しいインスタンスでは更新版が使用されます。",
+  "settings.opencode.update.failed": "OpenCode の更新に失敗しました。インストール済みバージョンは変更されていません。",
   "settings.configFiles.title": "設定ファイル",
   "settings.configFiles.subtitle": "このサーバーで許可リストに登録されたグローバル設定ファイルを編集します。",
   "settings.configFiles.selector.label": "ファイル",
@@ -151,6 +210,7 @@ export const settingsMessages = {
   "settings.configFiles.confirmDiscard.cancelLabel": "編集を続ける",
 
   "settings.providers.title": "プロバイダー認証",
+  "settings.providers.target": "OpenCode インスタンス: {workspace}",
   "settings.providers.subtitle": "アクティブな OpenCode インスタンスで使う API キーまたは OAuth アカウントを接続します。",
   "settings.providers.refresh": "更新",
   "settings.providers.selectProvider": "プロバイダーを選択",
@@ -208,8 +268,8 @@ export const settingsMessages = {
   "settings.providers.errors.envDisconnectUnavailable": "このプロバイダーは環境変数から設定されているため、UI から切断できません。",
 
   "settings.appearance.behavior.title": "操作",
-  "settings.appearance.behavior.subtitle": "メッセージ、差分、入力の既定値。",
-  "settings.behavior.expansionPresets.ariaLabel": "Transcript detail presets",
+  "settings.appearance.behavior.subtitle": "メッセージ、ツール、診断、使用量の詳細表示をまとめて制御します。",
+  "settings.behavior.expansionPresets.ariaLabel": "会話詳細プリセット",
   "settings.behavior.expansionPreset.minimal.title": "Minimal",
   "settings.behavior.expansionPreset.minimal.description": "Keep most generated detail tucked away until needed.",
   "settings.behavior.expansionPreset.balanced.title": "Balanced",
@@ -266,6 +326,7 @@ export const settingsMessages = {
   "settings.speech.status.loading": "設定を確認しています...",
   "settings.speech.status.configured": "設定済み",
   "settings.speech.status.missing": "APIキーがありません",
+  "settings.speech.status.partial": "一部設定済み",
   "settings.speech.status.error": "音声サービスを利用できません",
   "settings.speech.apiKey.title": "API キー",
   "settings.speech.apiKey.subtitle": "CodeNomadが管理する音声リクエストに使用されます。",
@@ -297,11 +358,44 @@ export const settingsMessages = {
   "settings.speech.testPlayback.stop": "サンプルを停止",
   "settings.speech.testPlayback.sample": "CodeNomad をご利用いただきありがとうございます。音声設定は正常に動作しています。",
   "settings.speech.testPlayback.note": "このテストは現在の再生モードと形式をすぐに使います。APIキー、Base URL、モデル、音声の変更も試したい場合は先に保存してください。",
+  "settings.speech.testInput.action": "入力をテスト",
+  "settings.speech.testInput.stop": "録音を停止",
+  "settings.speech.testInput.transcribing": "文字起こし中",
+  "settings.speech.testInput.requesting": "起動中…",
+  "settings.speech.testInput.empty": "音声が検出されませんでした",
   "settings.speech.save.action": "保存",
   "settings.speech.save.saving": "保存中...",
   "settings.speech.save.saved": "保存済み",
   "settings.speech.save.unsaved": "未保存の変更",
   "settings.speech.save.error": "保存に失敗しました",
+  "settings.speech.separateProviders.title": "入力と出力で異なるプロバイダーを使用",
+  "settings.speech.separateProviders.subtitle": "音声入力 (STT) と音声出力 (TTS) で異なる API キーとエンドポイントを使用します。",
+  "settings.speech.stt.section.title": "音声入力 (音声からテキスト)",
+  "settings.speech.tts.section.title": "音声出力 (テキストから音声)",
+  "settings.speech.stt.apiKey.title": "入力 API キー",
+  "settings.speech.stt.apiKey.subtitle": "音声からテキストのリクエストに使用されます。",
+  "settings.speech.stt.apiKey.placeholder": "新しい入力 API キーを入力",
+  "settings.speech.stt.apiKey.storedNote": "保存済みの入力 API キーは非表示です。新しい値を入力して置き換えるか、空欄のままにしてください。",
+  "settings.speech.stt.apiKey.usingShared": "共有 API キーを使用中。上書きするには新しいキーを入力してください。",
+  "settings.speech.stt.apiKey.clearAction": "保存済みの入力キーを削除",
+  "settings.speech.stt.apiKey.clearPending": "保存すると、保存済みの入力 API キーが削除されます。",
+  "settings.speech.stt.baseUrl.title": "入力ベース URL",
+  "settings.speech.stt.baseUrl.subtitle": "文字起こし用の OpenAI 互換エンドポイントです。",
+  "settings.speech.stt.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.stt.model.title": "入力モデル",
+  "settings.speech.stt.model.subtitle": "音声からテキストに使用するモデルです。",
+  "settings.speech.tts.apiKey.title": "出力 API キー",
+  "settings.speech.tts.apiKey.subtitle": "テキストから音声のリクエストに使用されます。",
+  "settings.speech.tts.apiKey.placeholder": "新しい出力 API キーを入力",
+  "settings.speech.tts.apiKey.storedNote": "保存済みの出力 API キーは非表示です。新しい値を入力して置き換えるか、空欄のままにしてください。",
+  "settings.speech.tts.apiKey.usingShared": "共有 API キーを使用中。上書きするには新しいキーを入力してください。",
+  "settings.speech.tts.apiKey.clearAction": "保存済みの出力キーを削除",
+  "settings.speech.tts.apiKey.clearPending": "保存すると、保存済みの出力 API キーが削除されます。",
+  "settings.speech.tts.baseUrl.title": "出力ベース URL",
+  "settings.speech.tts.baseUrl.subtitle": "音声合成用の OpenAI 互換エンドポイントです。",
+  "settings.speech.tts.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.tts.model.title": "出力モデル",
+  "settings.speech.tts.model.subtitle": "テキストから音声に使用するモデルです。",
   "settings.nav.sidecars": "SideCar",
   "settings.section.sidecars.eyebrow": "サーバーサービス",
   "settings.section.sidecars.title": "SideCar",
diff --git a/packages/ui/src/lib/i18n/messages/ne/commands.ts b/packages/ui/src/lib/i18n/messages/ne/commands.ts
index 89f1d10b..f7c9eab6 100644
--- a/packages/ui/src/lib/i18n/messages/ne/commands.ts
+++ b/packages/ui/src/lib/i18n/messages/ne/commands.ts
@@ -123,12 +123,12 @@ export const commandMessages = {
   "commands.diffViewUnified.keywords": "डिफ, एकीकृत, दृश्य",
 
   "commands.toolOutputsDefault.label": "उपकरण आउटपुट पूर्वनिर्धारित · {state}",
-  "commands.toolOutputsDefault.description": "उपकरण आउटपुटहरूको लागि पूर्वनिर्धारित विस्तार टगल गर्नुहोस्",
-  "commands.toolOutputsDefault.keywords": "उपकरण, आउटपुट, विस्तार, संकुचित",
+  "commands.toolOutputsDefault.description": "उपकरण आउटपुटहरूको पूर्वनिर्धारित दृश्यता सेट गर्नुहोस्",
+  "commands.toolOutputsDefault.keywords": "उपकरण, आउटपुट, लुकाउनुहोस्, विस्तार, संकुचित",
 
   "commands.diagnosticsDefault.label": "निदान (Diagnostics) पूर्वनिर्धारित · {state}",
-  "commands.diagnosticsDefault.description": "निदान आउटपुटको लागि पूर्वनिर्धारित विस्तार टगल गर्नुहोस्",
-  "commands.diagnosticsDefault.keywords": "निदान, विस्तार, संकुचित",
+  "commands.diagnosticsDefault.description": "निदान आउटपुटको पूर्वनिर्धारित दृश्यता सेट गर्नुहोस्",
+  "commands.diagnosticsDefault.keywords": "निदान, लुकाउनुहोस्, विस्तार, संकुचित",
 
   "commands.toolInputsVisibility.label": "उपकरण इनपुट दृश्यता · {state}",
   "commands.toolInputsVisibility.description": "उपकरण कल इनपुट तर्कहरूको लागि पूर्वनिर्धारित दृश्यता सेट गर्नुहोस्",
diff --git a/packages/ui/src/lib/i18n/messages/ne/folderSelection.ts b/packages/ui/src/lib/i18n/messages/ne/folderSelection.ts
index 6cf0e481..31f46c31 100644
--- a/packages/ui/src/lib/i18n/messages/ne/folderSelection.ts
+++ b/packages/ui/src/lib/i18n/messages/ne/folderSelection.ts
@@ -17,10 +17,8 @@ export const folderSelectionMessages = {
   "folderSelection.recent.rename": "कार्यस्थान पुन: नामकरण गर्नुहोस्",
   "folderSelection.recent.remove": "भर्खरको सूचीबाट हटाउनुहोस्",
   "folderSelection.recent.openBadge": "खोल्नुहोस्",
-  "folderSelection.recent.alreadyOpenTitle": "परियोजना पहिले नै खुला छ",
-  "folderSelection.recent.alreadyOpenMessage": "यो फोल्डर कसरी खोल्ने छनौट गर्नुहोस्।",
+  "folderSelection.recent.openNewInstance": "नयाँ इन्स्ट्यान्स खोल्नुहोस्",
   "folderSelection.recent.switchToOpenProject": "खुला परियोजनामा जानुहोस्",
-  "folderSelection.recent.openAnotherInstance": "अर्को उदाहरण खोल्नुहोस्",
 
   "folderSelection.browse.title": "फोल्डरको लागि ब्राउज गर्नुहोस्",
   "folderSelection.browse.subtitle": "तपाईंको कम्प्युटरमा कुनै पनि फोल्डर चयन गर्नुहोस्",
diff --git a/packages/ui/src/lib/i18n/messages/ne/instance.ts b/packages/ui/src/lib/i18n/messages/ne/instance.ts
index d1c1ab1f..7f5e938a 100644
--- a/packages/ui/src/lib/i18n/messages/ne/instance.ts
+++ b/packages/ui/src/lib/i18n/messages/ne/instance.ts
@@ -93,6 +93,19 @@ export const instanceMessages = {
   "instanceShell.rightPanel.tabs.files": "फाइलहरू",
   "instanceShell.rightPanel.tabs.status": "स्थिति",
   "instanceShell.rightPanel.tabs.ariaLabel": "दायाँ प्यानल ट्याबहरू",
+  "instanceShell.rightPanel.customize.toggle": "दायाँ प्यानल अनुकूलन गर्नुहोस्",
+  "instanceShell.rightPanel.customize.title": "दायाँ प्यानल अनुकूलन गर्नुहोस्",
+  "instanceShell.rightPanel.customize.description": "ट्याबहरू र स्थिति खण्डहरू देखाउनुहोस् वा लुकाउनुहोस्।",
+  "instanceShell.rightPanel.customize.reset": "रिसेट गर्नुहोस्",
+  "instanceShell.rightPanel.customize.tabs": "ट्याबहरू",
+  "instanceShell.rightPanel.customize.statusSections": "स्थिति खण्डहरू",
+  "instanceShell.rightPanel.customize.dragToReorder": "पुनःक्रमबद्ध गर्न ट्याब वा स्थिति खण्डहरू तान्नुहोस्।",
+  "instanceShell.rightPanel.customize.moveUp": "माथि",
+  "instanceShell.rightPanel.customize.moveDown": "तल",
+  "instanceShell.rightPanel.customize.moveTabUp": "{label} ट्याब माथि सार्नुहोस्",
+  "instanceShell.rightPanel.customize.moveTabDown": "{label} ट्याब तल सार्नुहोस्",
+  "instanceShell.rightPanel.customize.moveStatusSectionUp": "{label} स्थिति खण्ड माथि सार्नुहोस्",
+  "instanceShell.rightPanel.customize.moveStatusSectionDown": "{label} स्थिति खण्ड तल सार्नुहोस्",
   "instanceShell.rightPanel.actions.refresh": "रिफ्रेस",
   "instanceShell.rightPanel.actions.save": "बचत (Ctrl+S)",
   "instanceShell.rightPanel.actions.saveConfirm.message": "परिवर्तन गर्नु अघि \"{path}\" मा गरिएका परिवर्तनहरू बचत गर्न चाहनुहुन्छ?",
@@ -191,8 +204,8 @@ export const instanceMessages = {
 
   "instanceShell.yoloMode.noSessionSelected": "Yolo मोड कन्फिगर गर्न सत्र चयन गर्नुहोस्।",
   "instanceShell.yoloMode.title": "Yolo मोड",
-  "instanceShell.yoloMode.description": "यस सत्रको लागि अनुमति अनुरोधहरू स्वतः स्वीकृत गर्नुहोस्। पूर्वनिर्धारित रूपमा अक्षम।",
-  "instanceShell.yoloMode.badge": "Yolo मोड",
+  "instanceShell.yoloMode.description": "यस सत्रको लागि अनुमति अनुरोधहरू स्वतः स्वीकृत गर्नुहोस्।",
+  "instanceShell.yoloMode.badge": "Yolo",
   "instanceShell.yoloMode.badgeAriaLabel": "Yolo मोड सक्षम गरियो",
 
   "instanceShell.backgroundProcesses.empty": "कुनै पृष्ठभूमि प्रक्रियाहरू छैनन्।",
diff --git a/packages/ui/src/lib/i18n/messages/ne/markdown.ts b/packages/ui/src/lib/i18n/messages/ne/markdown.ts
index 842ceff7..defe0b09 100644
--- a/packages/ui/src/lib/i18n/messages/ne/markdown.ts
+++ b/packages/ui/src/lib/i18n/messages/ne/markdown.ts
@@ -2,6 +2,8 @@ export const markdownMessages = {
   "markdown.codeBlock.copy.label": "प्रतिलिपि गर्नुहोस्",
   "markdown.codeBlock.copy.copied": "प्रतिलिपि गरियो!",
   "markdown.codeBlock.copy.failed": "असफल",
+  "markdown.codeBlock.wrap.enable": "लाइन र्‍याप सक्षम गर्नुहोस्",
+  "markdown.codeBlock.wrap.disable": "लाइन र्‍याप असक्षम गर्नुहोस्",
 
   "markdown.copy": "प्रतिलिपि गर्नुहोस्",
 } as const
diff --git a/packages/ui/src/lib/i18n/messages/ne/messaging.ts b/packages/ui/src/lib/i18n/messages/ne/messaging.ts
index dd4579ed..5ba82e02 100644
--- a/packages/ui/src/lib/i18n/messages/ne/messaging.ts
+++ b/packages/ui/src/lib/i18n/messages/ne/messaging.ts
@@ -17,6 +17,7 @@ export const messagingMessages = {
   "messageSection.empty.tips.attachFilesPrefix": "यसको साथ फाइलहरू संलग्न गर्नुहोस्",
   "messageSection.loading.messages": "सन्देशहरू लोड गर्दै...",
   "messageSection.loadError.title": "सन्देशहरू लोड गर्न सकिएन",
+  "messageSection.loadError.detail": "OpenCode ले सत्रका सन्देशहरू फिर्ता गरेन।",
   "messageSection.loadError.reload": "सन्देशहरू फेरि लोड गर्नुहोस्",
   "messageSection.scroll.toFirstAriaLabel": "पहिलो सन्देशमा जानुहोस्",
   "messageSection.scroll.toLatestAriaLabel": "भर्खरको सन्देशमा जानुहोस्",
@@ -71,6 +72,8 @@ export const messagingMessages = {
   "messageBlock.usage.cacheRead": "क्यास पढाइ",
   "messageBlock.usage.cacheWrite": "क्यास लेखाइ",
   "messageBlock.usage.cost": "लागत (Cost)",
+  "messageBlock.usage.expandAriaLabel": "टोकन मेट्रिक्स विस्तार गर्नुहोस्",
+  "messageBlock.usage.collapseAriaLabel": "टोकन मेट्रिक्स संकुचित गर्नुहोस्",
   "messageBlock.step.agentLabel": "एजेन्ट: {agent}",
   "messageBlock.step.modelLabel": "मोडेल: {model}",
   "messageBlock.reasoning.thinkingLabel": "सोच्दै",
diff --git a/packages/ui/src/lib/i18n/messages/ne/session.ts b/packages/ui/src/lib/i18n/messages/ne/session.ts
index 267dac5f..96357251 100644
--- a/packages/ui/src/lib/i18n/messages/ne/session.ts
+++ b/packages/ui/src/lib/i18n/messages/ne/session.ts
@@ -15,6 +15,7 @@ export const sessionMessages = {
   "sessionList.status.working": "काम गर्दै",
   "sessionList.status.compacting": "संक्षिप्त गर्दै",
   "sessionList.status.idle": "निष्क्रिय",
+  "sessionList.status.interrupted": "अवरुद्ध",
   "sessionList.status.retrying": "पुन: प्रयास गर्दै",
   "sessionList.status.retryingIn": "{seconds} सेकेन्डमा पुन: प्रयास गर्दै",
   "sessionList.status.retryTooltip": "{message} (प्रयास {attempt})",
@@ -48,6 +49,10 @@ export const sessionMessages = {
   "sessionList.filter.placeholder": "सत्रहरू खोज्नुहोस्...",
   "sessionList.filter.ariaLabel": "सत्रहरू खोज्नुहोस्",
   "sessionList.loading.more": "थप सत्रहरू लोड गर्दै...",
+  "sessionList.loading.initial": "सत्रहरू लोड गर्दै...",
+  "sessionList.loadError.title": "सत्रहरू लोड गर्न सकिएन",
+  "sessionList.loadError.detail": "OpenCode ले सत्र सूची फिर्ता गरेन।",
+  "sessionList.loadError.retry": "पुन: प्रयास गर्नुहोस्",
   "sessionList.selection.selectAllLabel": "सबै चयन गर्नुहोस्",
   "sessionList.selection.selectAllAriaLabel": "सबै सत्रहरू चयन गर्नुहोस्",
   "sessionList.selection.clearLabel": "सफा गर्नुहोस्",
diff --git a/packages/ui/src/lib/i18n/messages/ne/settings.ts b/packages/ui/src/lib/i18n/messages/ne/settings.ts
index 0e474be7..cbfbb095 100644
--- a/packages/ui/src/lib/i18n/messages/ne/settings.ts
+++ b/packages/ui/src/lib/i18n/messages/ne/settings.ts
@@ -56,6 +56,7 @@ export const settingsMessages = {
   "contextUsagePanel.labels.input": "इनपुट",
   "contextUsagePanel.labels.output": "आउटपुट",
   "contextUsagePanel.labels.cost": "लागत",
+  "contextUsagePanel.included": "समावेश",
   "contextUsagePanel.labels.totalInput": "कुल इनपुट",
   "contextUsagePanel.labels.totalOutput": "कुल आउटपुट",
   "contextUsagePanel.labels.totalCost": "कुल लागत",
@@ -64,6 +65,32 @@ export const settingsMessages = {
   "contextUsagePanel.labels.available": "उपलब्ध",
   "contextUsagePanel.unavailable": "--",
 
+  "providerUsage.title": "प्रयोग",
+  "providerUsage.tooltip": "सक्रिय सत्रले चयन गरेको प्रदायकको प्रयोग र रिसेट अवधि।",
+  "providerUsage.noSession": "योजना प्रयोग हेर्न सत्र चयन गर्नुहोस्।",
+  "providerUsage.loading": "प्रयोग विवरण लोड हुँदैछ...",
+  "providerUsage.unsupported": "यो प्रदायकका लागि प्रयोग विवरण उपलब्ध छैन।",
+  "providerUsage.notConfigured": "मिल्दो सदस्यता प्रमाण फेला परेन।",
+  "providerUsage.unavailable": "प्रयोग विवरण अस्थायी रूपमा उपलब्ध छैन।",
+  "providerUsage.unavailableValue": "--",
+  "providerUsage.usedPercent": "{percent}% प्रयोग भयो",
+  "providerUsage.resets": "रिसेट {time}",
+  "providerUsage.progressLabel": "{window} योजना प्रयोग",
+  "providerUsage.windows.fiveHours": "५ घण्टा",
+  "providerUsage.windows.sevenDays": "७ दिन",
+  "providerUsage.windows.sevenDaysSonnet": "७ दिन · Sonnet",
+  "providerUsage.windows.sevenDaysOpus": "७ दिन · Opus",
+  "providerUsage.windows.weekly": "साप्ताहिक",
+  "providerUsage.windows.daily": "दैनिक",
+  "providerUsage.windows.monthly": "मासिक",
+  "providerUsage.windows.credits": "क्रेडिट",
+  "providerUsage.windows.billingCycle": "बिलिङ चक्र",
+  "providerUsage.windows.session": "सत्र",
+  "providerUsage.windows.premium": "प्रिमियम अनुरोध",
+  "providerUsage.windows.chat": "च्याट",
+  "providerUsage.windows.completions": "पूर्णता",
+  "providerUsage.windows.mcpTools": "MCP उपकरण",
+
   "settings.title": "सेटिङहरू",
   "settings.navigationAriaLabel": "सेटिङ खण्डहरू",
   "settings.close": "सेटिङहरू बन्द गर्नुहोस्",
@@ -71,6 +98,16 @@ export const settingsMessages = {
   "settings.open.title": "सेटिङहरू खोल्नुहोस्",
   "settings.open.ariaLabel": "सेटिङहरू खोल्नुहोस्",
   "settings.nav.appearance": "रूप (Appearance)",
+  "settings.nav.general": "सामान्य",
+  "settings.nav.chat": "च्याट",
+  "settings.nav.voice": "आवाज",
+  "settings.nav.connections": "जडानहरू",
+  "settings.nav.runtime": "रनटाइम",
+  "settings.nav.advanced": "उन्नत",
+  "settings.nav.about": "बारेमा",
+  "settings.general.language.subtitle": "सम्पूर्ण अनुप्रयोगमा प्रयोग हुने भाषा छान्नुहोस्।",
+  "settings.behavior.holdLongAssistantReplies.title": "लामो सहायक जवाफहरू रोक्नुहोस्",
+  "settings.behavior.holdLongAssistantReplies.subtitle": "स्ट्रिमिङ जवाफ दृश्यभन्दा बाहिर जाँदा स्वचालित पछ्याइ रोक्नुहोस्।",
   "settings.nav.notifications": "सूचनाहरू",
   "settings.nav.remote": "रिमोट पहुँच",
   "settings.nav.speech": "वाचन (Speech)",
@@ -89,6 +126,16 @@ export const settingsMessages = {
   "settings.appearance.theme.option.system": "तपाईंको अपरेटिङ सिस्टम सेटिङ अनुसार",
   "settings.appearance.theme.option.light": "उज्यालो रूप (Light appearance) प्रयोग गर्नुहोस्",
   "settings.appearance.theme.option.dark": "अँध्यारो रूप (Dark appearance) प्रयोग गर्नुहोस्",
+  "settings.appearance.startup.title": "सुरुआत",
+  "settings.appearance.startup.subtitle": "CodeNomad सुरु हुँदा यस यन्त्रमा के पुनर्स्थापना गर्ने छान्नुहोस्।",
+  "settings.appearance.startup.restore.title": "अघिल्लो अवस्था पुनर्स्थापना गर्नुहोस्",
+  "settings.appearance.startup.restore.subtitle": "कार्यस्थान र साइडकार ट्याब, सक्रिय सत्र र नपठाइएका सन्देशहरू फेरि खोल्नुहोस्, र स्क्रोल स्थिति, प्यानल लेआउट, विन्डोको स्थान र जुम पुनर्स्थापना गर्नुहोस्।",
+  "settings.appearance.startup.clear.title": "सुरक्षित सुरुआत अवस्था",
+  "settings.appearance.startup.clear.subtitle": "सुरक्षित ट्याब, मस्यौदा, स्क्रोल स्थिति र प्यानल लेआउट हटाउनुहोस्। CodeNomad र OpenCode का डेटा मेटिँदैनन्।",
+  "settings.appearance.startup.clear.action": "सुरक्षित अवस्था खाली गर्नुहोस्",
+  "settings.appearance.startup.clearSuccess": "सुरक्षित सुरुआत अवस्था खाली गरियो।",
+  "settings.appearance.startup.clearError": "सुरक्षित सुरुआत अवस्था खाली गर्न सकिएन।",
+  "settings.appearance.startup.updateError": "सुरुआत पुनर्स्थापना सेटिङ अद्यावधिक गर्न सकिएन।",
   "settings.section.notifications.title": "सूचनाहरू",
   "settings.section.notifications.subtitle": "सत्र गतिविधिको लागि OS-स्तर सूचनाहरू नियन्त्रण गर्नुहोस्।",
   "settings.notifications.permission.granted": "अनुमति दिइएको",
@@ -132,6 +179,18 @@ export const settingsMessages = {
   "settings.opencode.logLevel.option.info": "Info",
   "settings.opencode.logLevel.option.warn": "Warn",
   "settings.opencode.logLevel.option.error": "Error",
+  "settings.opencode.update.title": "OpenCode अद्यावधिकहरू",
+  "settings.opencode.update.subtitle": "कन्फिगर गरिएको OpenCode बाइनरीका अद्यावधिकहरू जाँच गरी स्थापना गर्नुहोस्।",
+  "settings.opencode.update.checking": "अद्यावधिकहरू जाँच गर्दै...",
+  "settings.opencode.update.checkFailed": "OpenCode अद्यावधिकहरू जाँच गर्न सकिएन।",
+  "settings.opencode.update.retry": "फेरि प्रयास गर्नुहोस्",
+  "settings.opencode.update.installed": "स्थापित संस्करण",
+  "settings.opencode.update.upToDate": "OpenCode अद्यावधिक छ।",
+  "settings.opencode.update.action": "OpenCode {version} मा अद्यावधिक गर्नुहोस्",
+  "settings.opencode.update.updating": "OpenCode अद्यावधिक गर्दै...",
+  "settings.opencode.update.requiresInstance": "अद्यावधिक स्थापना गर्न यो बाइनरीसँग कार्यस्थान सुरु गर्नुहोस्।",
+  "settings.opencode.update.success": "OpenCode {version} स्थापना भयो। नयाँ इन्स्ट्यान्सहरूले अद्यावधिक संस्करण प्रयोग गर्नेछन्।",
+  "settings.opencode.update.failed": "OpenCode अद्यावधिक असफल भयो। स्थापित संस्करण परिवर्तन गरिएको छैन।",
   "settings.configFiles.title": "कन्फिग फाइलहरू",
   "settings.configFiles.subtitle": "यस सर्भरमा विश्वस्त ग्लोबल कन्फिगरेसन फाइलहरू सम्पादन गर्नुहोस्।",
   "settings.configFiles.selector.label": "फाइल",
@@ -151,6 +210,7 @@ export const settingsMessages = {
   "settings.configFiles.confirmDiscard.cancelLabel": "सम्पादन जारी राख्नुहोस्",
 
   "settings.providers.title": "प्रदायक प्रमाणीकरण",
+  "settings.providers.target": "OpenCode इन्स्ट्यान्स: {workspace}",
   "settings.providers.subtitle": "सक्रिय OpenCode उदाहरणका लागि API कुञ्जीहरू वा OAuth खाताहरू जडान गर्नुहोस्।",
   "settings.providers.refresh": "रिफ्रेस",
   "settings.providers.selectProvider": "प्रदायक चयन गर्नुहोस्",
@@ -209,8 +269,8 @@ export const settingsMessages = {
 
 
   "settings.appearance.behavior.title": "अन्तरक्रिया",
-  "settings.appearance.behavior.subtitle": "सन्देश, डिफ र इनपुट पूर्वनिर्धारितहरू।",
-  "settings.behavior.expansionPresets.ariaLabel": "Transcript detail presets",
+  "settings.appearance.behavior.subtitle": "सन्देश, उपकरण, निदान र प्रयोग विवरण एकै ठाउँबाट नियन्त्रण गर्नुहोस्।",
+  "settings.behavior.expansionPresets.ariaLabel": "संवाद विवरण प्रिसेटहरू",
   "settings.behavior.expansionPreset.minimal.title": "Minimal",
   "settings.behavior.expansionPreset.minimal.description": "Keep most generated detail tucked away until needed.",
   "settings.behavior.expansionPreset.balanced.title": "Balanced",
@@ -267,6 +327,7 @@ export const settingsMessages = {
   "settings.speech.status.loading": "कन्फिगरेसन जाँच गर्दै...",
   "settings.speech.status.configured": "कन्फिगर गरियो",
   "settings.speech.status.missing": "API कुञ्जी हराइरहेको छ",
+  "settings.speech.status.partial": "आंशिक रूपमा कन्फिगर",
   "settings.speech.status.error": "वाचन सेवा उपलब्ध छैन",
   "settings.speech.apiKey.title": "API कुञ्जी",
   "settings.speech.apiKey.subtitle": "CodeNomad-व्यवस्थापित वाचन अनुरोधहरूको लागि प्रयोग गरिन्छ।",
@@ -298,11 +359,44 @@ export const settingsMessages = {
   "settings.speech.testPlayback.stop": "नमूना रोक्नुहोस्",
   "settings.speech.testPlayback.sample": "CodeNomad प्रयोग गर्नुभएकोमा धन्यवाद, तपाईंको वाचन सेटिङहरू ठीकसँग काम गरिरहेका छन्।",
   "settings.speech.testPlayback.note": "परीक्षणले तपाईंको हालको प्लेब्याक मोड र ढाँचा तुरुन्तै प्रयोग गर्दछ।",
+  "settings.speech.testInput.action": "इनपुट परीक्षण",
+  "settings.speech.testInput.stop": "रेकर्डिङ रोक्नुहोस्",
+  "settings.speech.testInput.transcribing": "ट्रान्सक्राइब गर्दै",
+  "settings.speech.testInput.requesting": "सुरु गर्दै…",
+  "settings.speech.testInput.empty": "आवाज पत्ता लागेन",
   "settings.speech.save.action": "बचत गर्नुहोस्",
   "settings.speech.save.saving": "बचत गर्दै...",
   "settings.speech.save.saved": "बचत गरियो",
   "settings.speech.save.unsaved": "बचत नगरिएका परिवर्तनहरू",
   "settings.speech.save.error": "बचत गर्न असफल भयो",
+  "settings.speech.separateProviders.title": "इनपुट र आउटपुटका लागि छुट्टाछुट्टै प्रदायक",
+  "settings.speech.separateProviders.subtitle": "आवाज इनपुट (STT) र आउटपुट (TTS) का लागि फरक API कुञ्जीहरू र एन्डपोइन्टहरू प्रयोग गर्नुहोस्।",
+  "settings.speech.stt.section.title": "आवाज इनपुट (आवाजबाट पाठ)",
+  "settings.speech.tts.section.title": "आवाज आउटपुट (पाठबाट आवाज)",
+  "settings.speech.stt.apiKey.title": "इनपुट API कुञ्जी",
+  "settings.speech.stt.apiKey.subtitle": "आवाजबाट-पाठ अनुरोधहरूको लागि प्रयोग गरिन्छ।",
+  "settings.speech.stt.apiKey.placeholder": "नयाँ इनपुट API कुञ्जी प्रविष्ट गर्नुहोस्",
+  "settings.speech.stt.apiKey.storedNote": "बचत गरिएको इनपुट API कुञ्जी लुकाइएको छ। प्रतिस्थापन गर्न नयाँ मान प्रविष्ट गर्नुहोस्।",
+  "settings.speech.stt.apiKey.usingShared": "साझा API कुञ्जी प्रयोग हुँदै। बदल्न नयाँ कुञ्जी प्रविष्ट गर्नुहोस्।",
+  "settings.speech.stt.apiKey.clearAction": "बचत गरिएको इनपुट कुञ्जी सफा गर्नुहोस्",
+  "settings.speech.stt.apiKey.clearPending": "बचत गर्दा बचत गरिएको इनपुट API कुञ्जी हटाइनेछ।",
+  "settings.speech.stt.baseUrl.title": "इनपुट आधार URL",
+  "settings.speech.stt.baseUrl.subtitle": "ट्रान्सक्रिप्सनका लागि OpenAI-संगत एन्डपोइन्ट।",
+  "settings.speech.stt.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.stt.model.title": "इनपुट मोडेल",
+  "settings.speech.stt.model.subtitle": "आवाजबाट पाठका लागि प्रयोग गरिने मोडेल।",
+  "settings.speech.tts.apiKey.title": "आउटपुट API कुञ्जी",
+  "settings.speech.tts.apiKey.subtitle": "पाठबाट-आवाज अनुरोधहरूको लागि प्रयोग गरिन्छ।",
+  "settings.speech.tts.apiKey.placeholder": "नयाँ आउटपुट API कुञ्जी प्रविष्ट गर्नुहोस्",
+  "settings.speech.tts.apiKey.storedNote": "बचत गरिएको आउटपुट API कुञ्जी लुकाइएको छ। प्रतिस्थापन गर्न नयाँ मान प्रविष्ट गर्नुहोस्।",
+  "settings.speech.tts.apiKey.usingShared": "साझा API कुञ्जी प्रयोग हुँदै। बदल्न नयाँ कुञ्जी प्रविष्ट गर्नुहोस्।",
+  "settings.speech.tts.apiKey.clearAction": "बचत गरिएको आउटपुट कुञ्जी सफा गर्नुहोस्",
+  "settings.speech.tts.apiKey.clearPending": "बचत गर्दा बचत गरिएको आउटपुट API कुञ्जी हटाइनेछ।",
+  "settings.speech.tts.baseUrl.title": "आउटपुट आधार URL",
+  "settings.speech.tts.baseUrl.subtitle": "सिन्थेसिसका लागि OpenAI-संगत एन्डपोइन्ट।",
+  "settings.speech.tts.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.tts.model.title": "आउटपुट मोडेल",
+  "settings.speech.tts.model.subtitle": "पाठबाट आवाजका लागि प्रयोग गरिने मोडेल।",
   "settings.nav.sidecars": "SideCars",
   "settings.section.sidecars.eyebrow": "सर्भर सेवाहरू",
   "settings.section.sidecars.title": "SideCars",
diff --git a/packages/ui/src/lib/i18n/messages/ru/commands.ts b/packages/ui/src/lib/i18n/messages/ru/commands.ts
index 3f1551a9..8d674f48 100644
--- a/packages/ui/src/lib/i18n/messages/ru/commands.ts
+++ b/packages/ui/src/lib/i18n/messages/ru/commands.ts
@@ -123,12 +123,12 @@ export const commandMessages = {
   "commands.diffViewUnified.keywords": "diff, unified, просмотр",
 
   "commands.toolOutputsDefault.label": "Выводы инструментов по умолчанию · {state}",
-  "commands.toolOutputsDefault.description": "Переключить, разворачивать ли выводы инструментов по умолчанию",
-  "commands.toolOutputsDefault.keywords": "tool, output, развернуть, свернуть",
+  "commands.toolOutputsDefault.description": "Задать видимость выводов инструментов по умолчанию",
+  "commands.toolOutputsDefault.keywords": "tool, output, скрыть, развернуть, свернуть",
 
   "commands.diagnosticsDefault.label": "Диагностика по умолчанию · {state}",
-  "commands.diagnosticsDefault.description": "Переключить, разворачивать ли вывод диагностики по умолчанию",
-  "commands.diagnosticsDefault.keywords": "diagnostics, развернуть, свернуть",
+  "commands.diagnosticsDefault.description": "Задать видимость вывода диагностики по умолчанию",
+  "commands.diagnosticsDefault.keywords": "diagnostics, скрыть, развернуть, свернуть",
 
   "commands.toolInputsVisibility.label": "Видимость входных данных инструмента · {state}",
   "commands.toolInputsVisibility.description": "Установить видимость аргументов входа вызовов инструментов по умолчанию",
diff --git a/packages/ui/src/lib/i18n/messages/ru/folderSelection.ts b/packages/ui/src/lib/i18n/messages/ru/folderSelection.ts
index 3229bd2f..bae2807a 100644
--- a/packages/ui/src/lib/i18n/messages/ru/folderSelection.ts
+++ b/packages/ui/src/lib/i18n/messages/ru/folderSelection.ts
@@ -17,10 +17,8 @@ export const folderSelectionMessages = {
   "folderSelection.recent.rename": "Переименовать рабочее пространство",
   "folderSelection.recent.remove": "Убрать из недавних",
   "folderSelection.recent.openBadge": "Открыта",
-  "folderSelection.recent.alreadyOpenTitle": "Проект уже открыт",
-  "folderSelection.recent.alreadyOpenMessage": "Выберите, как открыть эту папку.",
+  "folderSelection.recent.openNewInstance": "Открыть новый экземпляр",
   "folderSelection.recent.switchToOpenProject": "Перейти к открытому проекту",
-  "folderSelection.recent.openAnotherInstance": "Открыть еще одну инстанцию",
 
   "folderSelection.browse.title": "Выбрать папку",
   "folderSelection.browse.subtitle": "Выберите любую папку на компьютере",
diff --git a/packages/ui/src/lib/i18n/messages/ru/instance.ts b/packages/ui/src/lib/i18n/messages/ru/instance.ts
index 71054ec5..44386c15 100644
--- a/packages/ui/src/lib/i18n/messages/ru/instance.ts
+++ b/packages/ui/src/lib/i18n/messages/ru/instance.ts
@@ -93,6 +93,19 @@ export const instanceMessages = {
   "instanceShell.rightPanel.tabs.files": "Файлы",
   "instanceShell.rightPanel.tabs.status": "Статус",
   "instanceShell.rightPanel.tabs.ariaLabel": "Вкладки правой панели",
+  "instanceShell.rightPanel.customize.toggle": "Настроить правую панель",
+  "instanceShell.rightPanel.customize.title": "Настроить правую панель",
+  "instanceShell.rightPanel.customize.description": "Показывайте или скрывайте вкладки и секции статуса.",
+  "instanceShell.rightPanel.customize.reset": "Сбросить",
+  "instanceShell.rightPanel.customize.tabs": "Вкладки",
+  "instanceShell.rightPanel.customize.statusSections": "Секции статуса",
+  "instanceShell.rightPanel.customize.dragToReorder": "Перетаскивайте вкладки или секции статуса, чтобы изменить порядок.",
+  "instanceShell.rightPanel.customize.moveUp": "Вверх",
+  "instanceShell.rightPanel.customize.moveDown": "Вниз",
+  "instanceShell.rightPanel.customize.moveTabUp": "Переместить вкладку {label} вверх",
+  "instanceShell.rightPanel.customize.moveTabDown": "Переместить вкладку {label} вниз",
+  "instanceShell.rightPanel.customize.moveStatusSectionUp": "Переместить секцию статуса {label} вверх",
+  "instanceShell.rightPanel.customize.moveStatusSectionDown": "Переместить секцию статуса {label} вниз",
   "instanceShell.rightPanel.actions.refresh": "Обновить",
   "instanceShell.rightPanel.actions.save": "Сохранить (Ctrl+S)",
   "instanceShell.rightPanel.actions.saveConfirm.message": "Сохранить изменения в \"{path}\" перед переключением?",
@@ -167,7 +180,7 @@ export const instanceMessages = {
 
   "instanceShell.yoloMode.noSessionSelected": "Выберите сессию, чтобы настроить режим Yolo.",
   "instanceShell.yoloMode.title": "Режим Yolo",
-  "instanceShell.yoloMode.description": "Автоматически одобряет запросы разрешений для этой сессии. По умолчанию выключен.",
+  "instanceShell.yoloMode.description": "Автоматически одобряет запросы разрешений для этой сессии.",
   "instanceShell.yoloMode.badge": "Yolo",
   "instanceShell.yoloMode.badgeAriaLabel": "Режим Yolo включен",
 
diff --git a/packages/ui/src/lib/i18n/messages/ru/markdown.ts b/packages/ui/src/lib/i18n/messages/ru/markdown.ts
index 1c405038..ee4211f2 100644
--- a/packages/ui/src/lib/i18n/messages/ru/markdown.ts
+++ b/packages/ui/src/lib/i18n/messages/ru/markdown.ts
@@ -2,6 +2,8 @@ export const markdownMessages = {
   "markdown.codeBlock.copy.label": "Копировать",
   "markdown.codeBlock.copy.copied": "Скопировано!",
   "markdown.codeBlock.copy.failed": "Не удалось",
+  "markdown.codeBlock.wrap.enable": "Включить перенос строк",
+  "markdown.codeBlock.wrap.disable": "Отключить перенос строк",
 
   "markdown.copy": "Копировать",
 } as const
diff --git a/packages/ui/src/lib/i18n/messages/ru/messaging.ts b/packages/ui/src/lib/i18n/messages/ru/messaging.ts
index ee9ee7b5..02aaa1c3 100644
--- a/packages/ui/src/lib/i18n/messages/ru/messaging.ts
+++ b/packages/ui/src/lib/i18n/messages/ru/messaging.ts
@@ -17,6 +17,7 @@ export const messagingMessages = {
   "messageSection.empty.tips.attachFilesPrefix": "Прикрепляйте файлы через",
   "messageSection.loading.messages": "Загрузка сообщений…",
   "messageSection.loadError.title": "Не удалось загрузить сообщения",
+  "messageSection.loadError.detail": "OpenCode не вернул сообщения сессии.",
   "messageSection.loadError.reload": "Перезагрузить сообщения",
   "messageSection.scroll.toFirstAriaLabel": "Прокрутить к первому сообщению",
   "messageSection.scroll.toLatestAriaLabel": "Прокрутить к последнему сообщению",
@@ -73,6 +74,8 @@ export const messagingMessages = {
   "messageBlock.usage.cacheRead": "Чтение кэша",
   "messageBlock.usage.cacheWrite": "Запись кэша",
   "messageBlock.usage.cost": "Стоимость",
+  "messageBlock.usage.expandAriaLabel": "Развернуть метрики токенов",
+  "messageBlock.usage.collapseAriaLabel": "Свернуть метрики токенов",
   "messageBlock.step.agentLabel": "Агент: {agent}",
   "messageBlock.step.modelLabel": "Модель: {model}",
   "messageBlock.reasoning.thinkingLabel": "Размышления",
diff --git a/packages/ui/src/lib/i18n/messages/ru/session.ts b/packages/ui/src/lib/i18n/messages/ru/session.ts
index 888ee06b..0c8c29f1 100644
--- a/packages/ui/src/lib/i18n/messages/ru/session.ts
+++ b/packages/ui/src/lib/i18n/messages/ru/session.ts
@@ -15,6 +15,7 @@ export const sessionMessages = {
   "sessionList.status.working": "Работает",
   "sessionList.status.compacting": "Компактация",
   "sessionList.status.idle": "Простой",
+  "sessionList.status.interrupted": "Прервано",
   "sessionList.status.retrying": "Повтор",
   "sessionList.status.retryingIn": "Повтор через {seconds}с",
   "sessionList.status.retryTooltip": "{message} (Попытка {attempt})",
@@ -48,6 +49,10 @@ export const sessionMessages = {
   "sessionList.filter.placeholder": "Поиск сессий…",
   "sessionList.filter.ariaLabel": "Поиск сессий",
   "sessionList.loading.more": "Загрузка дополнительных сессий…",
+  "sessionList.loading.initial": "Загрузка сессий…",
+  "sessionList.loadError.title": "Не удалось загрузить сессии",
+  "sessionList.loadError.detail": "OpenCode не вернул список сессий.",
+  "sessionList.loadError.retry": "Повторить",
   "sessionList.selection.selectAllLabel": "Выбрать все",
   "sessionList.selection.selectAllAriaLabel": "Выбрать все сессии",
   "sessionList.selection.clearLabel": "Очистить",
diff --git a/packages/ui/src/lib/i18n/messages/ru/settings.ts b/packages/ui/src/lib/i18n/messages/ru/settings.ts
index 665f3e04..d364ab5a 100644
--- a/packages/ui/src/lib/i18n/messages/ru/settings.ts
+++ b/packages/ui/src/lib/i18n/messages/ru/settings.ts
@@ -56,6 +56,7 @@ export const settingsMessages = {
   "contextUsagePanel.labels.input": "Ввод",
   "contextUsagePanel.labels.output": "Вывод",
   "contextUsagePanel.labels.cost": "Стоимость",
+  "contextUsagePanel.included": "Включено",
   "contextUsagePanel.labels.totalInput": "Всего ввод",
   "contextUsagePanel.labels.totalOutput": "Всего вывод",
   "contextUsagePanel.labels.totalCost": "Общая стоимость",
@@ -64,6 +65,32 @@ export const settingsMessages = {
   "contextUsagePanel.labels.available": "Доступно",
   "contextUsagePanel.unavailable": "--",
 
+  "providerUsage.title": "Использование",
+  "providerUsage.tooltip": "Использование и периоды сброса провайдера, выбранного в активной сессии.",
+  "providerUsage.noSession": "Выберите сессию для просмотра использования тарифа.",
+  "providerUsage.loading": "Загрузка данных...",
+  "providerUsage.unsupported": "Данные об использовании недоступны для этого провайдера.",
+  "providerUsage.notConfigured": "Совместимые данные подписки не найдены.",
+  "providerUsage.unavailable": "Данные об использовании временно недоступны.",
+  "providerUsage.unavailableValue": "--",
+  "providerUsage.usedPercent": "Использовано {percent}%",
+  "providerUsage.resets": "Сброс {time}",
+  "providerUsage.progressLabel": "Использование тарифа {window}",
+  "providerUsage.windows.fiveHours": "5 часов",
+  "providerUsage.windows.sevenDays": "7 дней",
+  "providerUsage.windows.sevenDaysSonnet": "7 дней · Sonnet",
+  "providerUsage.windows.sevenDaysOpus": "7 дней · Opus",
+  "providerUsage.windows.weekly": "За неделю",
+  "providerUsage.windows.daily": "За день",
+  "providerUsage.windows.monthly": "За месяц",
+  "providerUsage.windows.credits": "Кредиты",
+  "providerUsage.windows.billingCycle": "Расчётный период",
+  "providerUsage.windows.session": "Сессия",
+  "providerUsage.windows.premium": "Премиум-запросы",
+  "providerUsage.windows.chat": "Чат",
+  "providerUsage.windows.completions": "Дополнения",
+  "providerUsage.windows.mcpTools": "Инструменты MCP",
+
   "settings.title": "Настройки",
   "settings.navigationAriaLabel": "Разделы настроек",
   "settings.close": "Закрыть настройки",
@@ -71,6 +98,16 @@ export const settingsMessages = {
   "settings.open.title": "Открыть настройки",
   "settings.open.ariaLabel": "Открыть настройки",
   "settings.nav.appearance": "Внешний вид",
+  "settings.nav.general": "Общие",
+  "settings.nav.chat": "Чат",
+  "settings.nav.voice": "Голос",
+  "settings.nav.connections": "Подключения",
+  "settings.nav.runtime": "Среда выполнения",
+  "settings.nav.advanced": "Расширенные",
+  "settings.nav.about": "О программе",
+  "settings.general.language.subtitle": "Выберите язык, используемый во всём приложении.",
+  "settings.behavior.holdLongAssistantReplies.title": "Удерживать длинные ответы ассистента",
+  "settings.behavior.holdLongAssistantReplies.subtitle": "Прекращать автоматическое следование, когда потоковый ответ выходит за пределы окна.",
   "settings.nav.notifications": "Уведомления",
   "settings.nav.remote": "Удалённый доступ",
   "settings.nav.speech": "Речь",
@@ -89,6 +126,16 @@ export const settingsMessages = {
   "settings.appearance.theme.option.system": "Следовать настройкам операционной системы",
   "settings.appearance.theme.option.light": "Использовать светлую тему",
   "settings.appearance.theme.option.dark": "Использовать тёмную тему",
+  "settings.appearance.startup.title": "Запуск",
+  "settings.appearance.startup.subtitle": "Выберите, что восстанавливать на этом устройстве при запуске CodeNomad.",
+  "settings.appearance.startup.restore.title": "Восстанавливать предыдущее состояние",
+  "settings.appearance.startup.restore.subtitle": "Повторно открывать вкладки рабочих пространств и sidecar, активные сессии и неотправленные сообщения, а также восстанавливать позиции прокрутки, расположение панелей, положение окна и масштаб.",
+  "settings.appearance.startup.clear.title": "Сохранённое состояние запуска",
+  "settings.appearance.startup.clear.subtitle": "Удалить сохранённые вкладки, черновики, позиции прокрутки и расположение панелей. Данные CodeNomad и OpenCode не удаляются.",
+  "settings.appearance.startup.clear.action": "Очистить сохранённое состояние",
+  "settings.appearance.startup.clearSuccess": "Сохранённое состояние запуска очищено.",
+  "settings.appearance.startup.clearError": "Не удалось очистить сохранённое состояние запуска.",
+  "settings.appearance.startup.updateError": "Не удалось обновить настройку восстановления при запуске.",
   "settings.section.notifications.title": "Уведомления",
   "settings.section.notifications.subtitle": "Управляйте системными уведомлениями об активности сессий.",
   "settings.notifications.permission.granted": "Разрешены",
@@ -132,6 +179,18 @@ export const settingsMessages = {
   "settings.opencode.logLevel.option.info": "Информация",
   "settings.opencode.logLevel.option.warn": "Предупреждение",
   "settings.opencode.logLevel.option.error": "Ошибка",
+  "settings.opencode.update.title": "Обновления OpenCode",
+  "settings.opencode.update.subtitle": "Проверка и установка обновлений настроенного бинарного файла OpenCode.",
+  "settings.opencode.update.checking": "Проверка обновлений...",
+  "settings.opencode.update.checkFailed": "Не удалось проверить обновления OpenCode.",
+  "settings.opencode.update.retry": "Повторить",
+  "settings.opencode.update.installed": "Установленная версия",
+  "settings.opencode.update.upToDate": "OpenCode обновлён до последней версии.",
+  "settings.opencode.update.action": "Обновить до OpenCode {version}",
+  "settings.opencode.update.updating": "Обновление OpenCode...",
+  "settings.opencode.update.requiresInstance": "Запустите рабочее пространство с этим бинарным файлом, чтобы установить обновление.",
+  "settings.opencode.update.success": "OpenCode {version} установлен. Новые экземпляры будут использовать обновлённую версию.",
+  "settings.opencode.update.failed": "Не удалось обновить OpenCode. Установленная версия не изменилась.",
   "settings.configFiles.title": "Файлы конфигурации",
   "settings.configFiles.subtitle": "Редактируйте разрешённые глобальные файлы конфигурации на этом сервере.",
   "settings.configFiles.selector.label": "Файл",
@@ -151,6 +210,7 @@ export const settingsMessages = {
   "settings.configFiles.confirmDiscard.cancelLabel": "Продолжить редактирование",
 
   "settings.providers.title": "Аутентификация провайдеров",
+  "settings.providers.target": "Экземпляр OpenCode: {workspace}",
   "settings.providers.subtitle": "Подключите API-ключи или OAuth-аккаунты для активного экземпляра OpenCode.",
   "settings.providers.refresh": "Обновить",
   "settings.providers.selectProvider": "Выберите провайдера",
@@ -208,8 +268,8 @@ export const settingsMessages = {
   "settings.providers.errors.envDisconnectUnavailable": "Этот провайдер настроен через переменные окружения и не может быть отключён из интерфейса.",
 
   "settings.appearance.behavior.title": "Взаимодействие",
-  "settings.appearance.behavior.subtitle": "Значения по умолчанию для сообщений, диффов и ввода.",
-  "settings.behavior.expansionPresets.ariaLabel": "Transcript detail presets",
+  "settings.appearance.behavior.subtitle": "Общее управление детализацией сообщений, инструментов, диагностики и использования.",
+  "settings.behavior.expansionPresets.ariaLabel": "Предустановки детализации диалога",
   "settings.behavior.expansionPreset.minimal.title": "Minimal",
   "settings.behavior.expansionPreset.minimal.description": "Keep most generated detail tucked away until needed.",
   "settings.behavior.expansionPreset.balanced.title": "Balanced",
@@ -266,6 +326,7 @@ export const settingsMessages = {
   "settings.speech.status.loading": "Проверка конфигурации...",
   "settings.speech.status.configured": "Настроено",
   "settings.speech.status.missing": "Отсутствует API-ключ",
+  "settings.speech.status.partial": "Частично настроено",
   "settings.speech.status.error": "Речевой сервис недоступен",
   "settings.speech.apiKey.title": "API-ключ",
   "settings.speech.apiKey.subtitle": "Используется для речевых запросов, управляемых CodeNomad.",
@@ -297,11 +358,44 @@ export const settingsMessages = {
   "settings.speech.testPlayback.stop": "Остановить пример",
   "settings.speech.testPlayback.sample": "Спасибо, что используете CodeNomad, ваши настройки речи работают нормально.",
   "settings.speech.testPlayback.note": "Тест сразу использует текущие режим и формат. Сначала сохраните изменения API key, Base URL, модели или голоса, если хотите проверить и их.",
+  "settings.speech.testInput.action": "Проверить ввод",
+  "settings.speech.testInput.stop": "Остановить запись",
+  "settings.speech.testInput.transcribing": "Транскрибация",
+  "settings.speech.testInput.requesting": "Запуск…",
+  "settings.speech.testInput.empty": "Речь не обнаружена",
   "settings.speech.save.action": "Сохранить",
   "settings.speech.save.saving": "Сохранение...",
   "settings.speech.save.saved": "Сохранено",
   "settings.speech.save.unsaved": "Есть несохранённые изменения",
   "settings.speech.save.error": "Не удалось сохранить",
+  "settings.speech.separateProviders.title": "Раздельные провайдеры для ввода и вывода",
+  "settings.speech.separateProviders.subtitle": "Использовать разные API-ключи и эндпоинты для голосового ввода (STT) и вывода (TTS).",
+  "settings.speech.stt.section.title": "Голосовой ввод (речь в текст)",
+  "settings.speech.tts.section.title": "Голосовой вывод (текст в речь)",
+  "settings.speech.stt.apiKey.title": "API-ключ для ввода",
+  "settings.speech.stt.apiKey.subtitle": "Используется для запросов преобразования речи в текст.",
+  "settings.speech.stt.apiKey.placeholder": "Введите новый API-ключ для ввода",
+  "settings.speech.stt.apiKey.storedNote": "Сохранённый API-ключ для ввода скрыт. Введите новое значение, чтобы заменить его.",
+  "settings.speech.stt.apiKey.usingShared": "Используется общий API-ключ. Введите новый ключ для замены.",
+  "settings.speech.stt.apiKey.clearAction": "Очистить сохранённый ключ ввода",
+  "settings.speech.stt.apiKey.clearPending": "Сохранённый API-ключ для ввода будет удалён при сохранении.",
+  "settings.speech.stt.baseUrl.title": "Базовый URL для ввода",
+  "settings.speech.stt.baseUrl.subtitle": "OpenAI-совместимый эндпоинт для транскрипции.",
+  "settings.speech.stt.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.stt.model.title": "Модель ввода",
+  "settings.speech.stt.model.subtitle": "Модель, используемая для преобразования речи в текст.",
+  "settings.speech.tts.apiKey.title": "API-ключ для вывода",
+  "settings.speech.tts.apiKey.subtitle": "Используется для запросов преобразования текста в речь.",
+  "settings.speech.tts.apiKey.placeholder": "Введите новый API-ключ для вывода",
+  "settings.speech.tts.apiKey.storedNote": "Сохранённый API-ключ для вывода скрыт. Введите новое значение, чтобы заменить его.",
+  "settings.speech.tts.apiKey.usingShared": "Используется общий API-ключ. Введите новый ключ для замены.",
+  "settings.speech.tts.apiKey.clearAction": "Очистить сохранённый ключ вывода",
+  "settings.speech.tts.apiKey.clearPending": "Сохранённый API-ключ для вывода будет удалён при сохранении.",
+  "settings.speech.tts.baseUrl.title": "Базовый URL для вывода",
+  "settings.speech.tts.baseUrl.subtitle": "OpenAI-совместимый эндпоинт для синтеза речи.",
+  "settings.speech.tts.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.tts.model.title": "Модель вывода",
+  "settings.speech.tts.model.subtitle": "Модель, используемая для преобразования текста в речь.",
   "settings.nav.sidecars": "SideCars",
   "settings.section.sidecars.eyebrow": "Серверные сервисы",
   "settings.section.sidecars.title": "SideCars",
diff --git a/packages/ui/src/lib/i18n/messages/zh-Hans/commands.ts b/packages/ui/src/lib/i18n/messages/zh-Hans/commands.ts
index e3c31d41..a8078c14 100644
--- a/packages/ui/src/lib/i18n/messages/zh-Hans/commands.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-Hans/commands.ts
@@ -123,12 +123,12 @@ export const commandMessages = {
   "commands.diffViewUnified.keywords": "diff, unified, view, 差异, 统一, 视图",
 
   "commands.toolOutputsDefault.label": "工具输出默认 · {state}",
-  "commands.toolOutputsDefault.description": "切换工具输出是否默认展开",
-  "commands.toolOutputsDefault.keywords": "tool, output, expand, collapse, 工具, 输出, 展开, 折叠",
+  "commands.toolOutputsDefault.description": "设置工具输出的默认可见性",
+  "commands.toolOutputsDefault.keywords": "tool, output, hide, expand, collapse, 工具, 输出, 隐藏, 展开, 折叠",
 
   "commands.diagnosticsDefault.label": "诊断默认 · {state}",
-  "commands.diagnosticsDefault.description": "切换诊断输出是否默认展开",
-  "commands.diagnosticsDefault.keywords": "diagnostics, expand, collapse, 诊断, 展开, 折叠",
+  "commands.diagnosticsDefault.description": "设置诊断输出的默认可见性",
+  "commands.diagnosticsDefault.keywords": "diagnostics, hide, expand, collapse, 诊断, 隐藏, 展开, 折叠",
 
   "commands.toolInputsVisibility.label": "工具输入可见性 · {state}",
   "commands.toolInputsVisibility.description": "设置工具调用输入参数的默认可见性",
diff --git a/packages/ui/src/lib/i18n/messages/zh-Hans/folderSelection.ts b/packages/ui/src/lib/i18n/messages/zh-Hans/folderSelection.ts
index 21b2410e..f168c2de 100644
--- a/packages/ui/src/lib/i18n/messages/zh-Hans/folderSelection.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-Hans/folderSelection.ts
@@ -17,10 +17,8 @@ export const folderSelectionMessages = {
   "folderSelection.recent.rename": "重命名工作区",
   "folderSelection.recent.remove": "从最近列表移除",
   "folderSelection.recent.openBadge": "已打开",
-  "folderSelection.recent.alreadyOpenTitle": "项目已打开",
-  "folderSelection.recent.alreadyOpenMessage": "选择如何打开此文件夹。",
+  "folderSelection.recent.openNewInstance": "打开新实例",
   "folderSelection.recent.switchToOpenProject": "切换到已打开的项目",
-  "folderSelection.recent.openAnotherInstance": "打开另一个实例",
 
   "folderSelection.browse.title": "浏览文件夹",
   "folderSelection.browse.subtitle": "选择你电脑上的任意文件夹",
diff --git a/packages/ui/src/lib/i18n/messages/zh-Hans/instance.ts b/packages/ui/src/lib/i18n/messages/zh-Hans/instance.ts
index 3e5c33ed..f1bb74eb 100644
--- a/packages/ui/src/lib/i18n/messages/zh-Hans/instance.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-Hans/instance.ts
@@ -93,6 +93,19 @@ export const instanceMessages = {
   "instanceShell.rightPanel.tabs.files": "文件",
   "instanceShell.rightPanel.tabs.status": "状态",
   "instanceShell.rightPanel.tabs.ariaLabel": "右侧面板标签页",
+  "instanceShell.rightPanel.customize.toggle": "自定义右侧面板",
+  "instanceShell.rightPanel.customize.title": "自定义右侧面板",
+  "instanceShell.rightPanel.customize.description": "显示或隐藏标签页和状态分区。",
+  "instanceShell.rightPanel.customize.reset": "重置",
+  "instanceShell.rightPanel.customize.tabs": "标签页",
+  "instanceShell.rightPanel.customize.statusSections": "状态分区",
+  "instanceShell.rightPanel.customize.dragToReorder": "拖动标签页或状态分区以重新排序。",
+  "instanceShell.rightPanel.customize.moveUp": "上移",
+  "instanceShell.rightPanel.customize.moveDown": "下移",
+  "instanceShell.rightPanel.customize.moveTabUp": "上移 {label} 标签页",
+  "instanceShell.rightPanel.customize.moveTabDown": "下移 {label} 标签页",
+  "instanceShell.rightPanel.customize.moveStatusSectionUp": "上移 {label} 状态分区",
+  "instanceShell.rightPanel.customize.moveStatusSectionDown": "下移 {label} 状态分区",
   "instanceShell.rightPanel.actions.refresh": "刷新",
   "instanceShell.rightPanel.actions.save": "保存 (Ctrl+S)",
   "instanceShell.rightPanel.actions.saveConfirm.message": "切换前是否保存对 \"{path}\" 的更改？",
@@ -167,7 +180,7 @@ export const instanceMessages = {
 
   "instanceShell.yoloMode.noSessionSelected": "请选择一个会话来配置 Yolo 模式。",
   "instanceShell.yoloMode.title": "Yolo 模式",
-  "instanceShell.yoloMode.description": "自动批准此会话的权限请求。默认关闭。",
+  "instanceShell.yoloMode.description": "自动批准此会话的权限请求。",
   "instanceShell.yoloMode.badge": "Yolo",
   "instanceShell.yoloMode.badgeAriaLabel": "Yolo 模式已启用",
 
diff --git a/packages/ui/src/lib/i18n/messages/zh-Hans/markdown.ts b/packages/ui/src/lib/i18n/messages/zh-Hans/markdown.ts
index 0bae2824..dfcb3fe5 100644
--- a/packages/ui/src/lib/i18n/messages/zh-Hans/markdown.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-Hans/markdown.ts
@@ -2,6 +2,8 @@ export const markdownMessages = {
   "markdown.codeBlock.copy.label": "复制",
   "markdown.codeBlock.copy.copied": "已复制！",
   "markdown.codeBlock.copy.failed": "失败",
+  "markdown.codeBlock.wrap.enable": "启用自动换行",
+  "markdown.codeBlock.wrap.disable": "禁用自动换行",
 
   "markdown.copy": "复制",
 } as const
diff --git a/packages/ui/src/lib/i18n/messages/zh-Hans/messaging.ts b/packages/ui/src/lib/i18n/messages/zh-Hans/messaging.ts
index 4e28fd93..bb36a381 100644
--- a/packages/ui/src/lib/i18n/messages/zh-Hans/messaging.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-Hans/messaging.ts
@@ -17,6 +17,7 @@ export const messagingMessages = {
   "messageSection.empty.tips.attachFilesPrefix": "通过以下方式附加文件",
   "messageSection.loading.messages": "正在加载消息...",
   "messageSection.loadError.title": "无法加载消息",
+  "messageSection.loadError.detail": "OpenCode 未返回会话消息。",
   "messageSection.loadError.reload": "重新加载消息",
   "messageSection.scroll.toFirstAriaLabel": "滚动到第一条消息",
   "messageSection.scroll.toLatestAriaLabel": "滚动到最新消息",
@@ -73,6 +74,8 @@ export const messagingMessages = {
   "messageBlock.usage.cacheRead": "缓存读取",
   "messageBlock.usage.cacheWrite": "缓存写入",
   "messageBlock.usage.cost": "费用",
+  "messageBlock.usage.expandAriaLabel": "展开令牌指标",
+  "messageBlock.usage.collapseAriaLabel": "折叠令牌指标",
   "messageBlock.step.agentLabel": "智能体：{agent}",
   "messageBlock.step.modelLabel": "模型：{model}",
   "messageBlock.reasoning.thinkingLabel": "思考",
diff --git a/packages/ui/src/lib/i18n/messages/zh-Hans/session.ts b/packages/ui/src/lib/i18n/messages/zh-Hans/session.ts
index f4dc3d96..53ff2fde 100644
--- a/packages/ui/src/lib/i18n/messages/zh-Hans/session.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-Hans/session.ts
@@ -15,6 +15,7 @@ export const sessionMessages = {
   "sessionList.status.working": "工作中",
   "sessionList.status.compacting": "压缩中",
   "sessionList.status.idle": "空闲",
+  "sessionList.status.interrupted": "已中断",
   "sessionList.status.retrying": "重试中",
   "sessionList.status.retryingIn": "{seconds} 秒后重试",
   "sessionList.status.retryTooltip": "{message}（第 {attempt} 次尝试）",
@@ -48,6 +49,10 @@ export const sessionMessages = {
   "sessionList.filter.placeholder": "搜索会话…",
   "sessionList.filter.ariaLabel": "搜索会话",
   "sessionList.loading.more": "正在加载更多会话…",
+  "sessionList.loading.initial": "正在加载会话…",
+  "sessionList.loadError.title": "无法加载会话",
+  "sessionList.loadError.detail": "OpenCode 未返回会话列表。",
+  "sessionList.loadError.retry": "重试",
   "sessionList.selection.selectAllLabel": "全选",
   "sessionList.selection.selectAllAriaLabel": "选择所有会话",
   "sessionList.selection.clearLabel": "清除",
diff --git a/packages/ui/src/lib/i18n/messages/zh-Hans/settings.ts b/packages/ui/src/lib/i18n/messages/zh-Hans/settings.ts
index fc9706c7..1eed86ce 100644
--- a/packages/ui/src/lib/i18n/messages/zh-Hans/settings.ts
+++ b/packages/ui/src/lib/i18n/messages/zh-Hans/settings.ts
@@ -56,6 +56,7 @@ export const settingsMessages = {
   "contextUsagePanel.labels.input": "输入",
   "contextUsagePanel.labels.output": "输出",
   "contextUsagePanel.labels.cost": "费用",
+  "contextUsagePanel.included": "已包含",
   "contextUsagePanel.labels.totalInput": "总输入",
   "contextUsagePanel.labels.totalOutput": "总输出",
   "contextUsagePanel.labels.totalCost": "总费用",
@@ -64,6 +65,32 @@ export const settingsMessages = {
   "contextUsagePanel.labels.available": "可用",
   "contextUsagePanel.unavailable": "--",
 
+  "providerUsage.title": "用量",
+  "providerUsage.tooltip": "活动会话所选提供商的用量和重置周期。",
+  "providerUsage.noSession": "请选择一个会话以查看套餐用量。",
+  "providerUsage.loading": "正在加载用量...",
+  "providerUsage.unsupported": "此提供商不支持用量查询。",
+  "providerUsage.notConfigured": "未找到兼容的订阅凭据。",
+  "providerUsage.unavailable": "用量暂时不可用。",
+  "providerUsage.unavailableValue": "--",
+  "providerUsage.usedPercent": "已使用 {percent}%",
+  "providerUsage.resets": "重置时间 {time}",
+  "providerUsage.progressLabel": "{window} 套餐用量",
+  "providerUsage.windows.fiveHours": "5 小时",
+  "providerUsage.windows.sevenDays": "7 天",
+  "providerUsage.windows.sevenDaysSonnet": "7 天 · Sonnet",
+  "providerUsage.windows.sevenDaysOpus": "7 天 · Opus",
+  "providerUsage.windows.weekly": "每周",
+  "providerUsage.windows.daily": "每日",
+  "providerUsage.windows.monthly": "每月",
+  "providerUsage.windows.credits": "额度",
+  "providerUsage.windows.billingCycle": "计费周期",
+  "providerUsage.windows.session": "会话",
+  "providerUsage.windows.premium": "高级请求",
+  "providerUsage.windows.chat": "聊天",
+  "providerUsage.windows.completions": "补全",
+  "providerUsage.windows.mcpTools": "MCP 工具",
+
   "settings.title": "设置",
   "settings.navigationAriaLabel": "设置分区",
   "settings.close": "关闭设置",
@@ -71,6 +98,16 @@ export const settingsMessages = {
   "settings.open.title": "打开设置",
   "settings.open.ariaLabel": "打开设置",
   "settings.nav.appearance": "外观",
+  "settings.nav.general": "常规",
+  "settings.nav.chat": "聊天",
+  "settings.nav.voice": "语音",
+  "settings.nav.connections": "连接",
+  "settings.nav.runtime": "运行时",
+  "settings.nav.advanced": "高级",
+  "settings.nav.about": "关于",
+  "settings.general.language.subtitle": "选择整个应用程序使用的语言。",
+  "settings.behavior.holdLongAssistantReplies.title": "暂停跟随较长的助手回复",
+  "settings.behavior.holdLongAssistantReplies.subtitle": "当流式回复超出视口时停止自动跟随。",
   "settings.nav.notifications": "通知",
   "settings.nav.remote": "远程访问",
   "settings.nav.speech": "语音",
@@ -89,6 +126,16 @@ export const settingsMessages = {
   "settings.appearance.theme.option.system": "跟随操作系统设置",
   "settings.appearance.theme.option.light": "使用浅色外观",
   "settings.appearance.theme.option.dark": "使用深色外观",
+  "settings.appearance.startup.title": "启动",
+  "settings.appearance.startup.subtitle": "选择 CodeNomad 启动时在此设备上恢复的内容。",
+  "settings.appearance.startup.restore.title": "恢复上次状态",
+  "settings.appearance.startup.restore.subtitle": "重新打开工作区和边栏标签页、活动会话和未发送的消息，并恢复滚动位置、面板布局、窗口位置和缩放级别。",
+  "settings.appearance.startup.clear.title": "已保存的启动状态",
+  "settings.appearance.startup.clear.subtitle": "移除已保存的标签页、草稿、滚动位置和面板布局。不会删除 CodeNomad 或 OpenCode 数据。",
+  "settings.appearance.startup.clear.action": "清除已保存状态",
+  "settings.appearance.startup.clearSuccess": "已清除保存的启动状态。",
+  "settings.appearance.startup.clearError": "无法清除保存的启动状态。",
+  "settings.appearance.startup.updateError": "无法更新启动恢复设置。",
   "settings.section.notifications.title": "通知",
   "settings.section.notifications.subtitle": "控制会话活动的系统级通知。",
   "settings.notifications.permission.granted": "已授予",
@@ -132,6 +179,18 @@ export const settingsMessages = {
   "settings.opencode.logLevel.option.info": "信息",
   "settings.opencode.logLevel.option.warn": "警告",
   "settings.opencode.logLevel.option.error": "错误",
+  "settings.opencode.update.title": "OpenCode 更新",
+  "settings.opencode.update.subtitle": "检查并安装已配置 OpenCode 可执行文件的更新。",
+  "settings.opencode.update.checking": "正在检查更新...",
+  "settings.opencode.update.checkFailed": "无法检查 OpenCode 更新。",
+  "settings.opencode.update.retry": "重试",
+  "settings.opencode.update.installed": "已安装版本",
+  "settings.opencode.update.upToDate": "OpenCode 已是最新版本。",
+  "settings.opencode.update.action": "更新到 OpenCode {version}",
+  "settings.opencode.update.updating": "正在更新 OpenCode...",
+  "settings.opencode.update.requiresInstance": "请使用此可执行文件启动工作区以安装更新。",
+  "settings.opencode.update.success": "OpenCode {version} 已安装。新实例将使用更新后的版本。",
+  "settings.opencode.update.failed": "OpenCode 更新失败。已安装的版本未更改。",
   "settings.configFiles.title": "配置文件",
   "settings.configFiles.subtitle": "编辑此服务器允许列表中的全局配置文件。",
   "settings.configFiles.selector.label": "文件",
@@ -151,6 +210,7 @@ export const settingsMessages = {
   "settings.configFiles.confirmDiscard.cancelLabel": "继续编辑",
 
   "settings.providers.title": "提供商认证",
+  "settings.providers.target": "OpenCode 实例：{workspace}",
   "settings.providers.subtitle": "为当前 OpenCode 实例连接 API 密钥或 OAuth 账号。",
   "settings.providers.refresh": "刷新",
   "settings.providers.selectProvider": "选择提供商",
@@ -208,8 +268,8 @@ export const settingsMessages = {
   "settings.providers.errors.envDisconnectUnavailable": "此提供商由环境变量配置，无法从界面断开连接。",
 
   "settings.appearance.behavior.title": "交互",
-  "settings.appearance.behavior.subtitle": "消息、差异与输入的默认值。",
-  "settings.behavior.expansionPresets.ariaLabel": "Transcript detail presets",
+  "settings.appearance.behavior.subtitle": "统一控制消息、工具、诊断和用量详情。",
+  "settings.behavior.expansionPresets.ariaLabel": "对话详情预设",
   "settings.behavior.expansionPreset.minimal.title": "Minimal",
   "settings.behavior.expansionPreset.minimal.description": "Keep most generated detail tucked away until needed.",
   "settings.behavior.expansionPreset.balanced.title": "Balanced",
@@ -266,6 +326,7 @@ export const settingsMessages = {
   "settings.speech.status.loading": "正在检查配置...",
   "settings.speech.status.configured": "已配置",
   "settings.speech.status.missing": "缺少 API 密钥",
+  "settings.speech.status.partial": "部分已配置",
   "settings.speech.status.error": "语音服务不可用",
   "settings.speech.apiKey.title": "API 密钥",
   "settings.speech.apiKey.subtitle": "用于 CodeNomad 管理的语音请求。",
@@ -297,11 +358,44 @@ export const settingsMessages = {
   "settings.speech.testPlayback.stop": "停止示例",
   "settings.speech.testPlayback.sample": "感谢你使用 CodeNomad，你的语音设置工作正常。",
   "settings.speech.testPlayback.note": "测试会立即使用当前播放模式和格式。如果你也想测试 API key、Base URL、模型或音色的更改，请先保存。",
+  "settings.speech.testInput.action": "测试输入",
+  "settings.speech.testInput.stop": "停止录音",
+  "settings.speech.testInput.transcribing": "转录中",
+  "settings.speech.testInput.requesting": "启动中…",
+  "settings.speech.testInput.empty": "未检测到语音",
   "settings.speech.save.action": "保存",
   "settings.speech.save.saving": "保存中...",
   "settings.speech.save.saved": "已保存",
   "settings.speech.save.unsaved": "有未保存的更改",
   "settings.speech.save.error": "保存失败",
+  "settings.speech.separateProviders.title": "为输入和输出使用不同供应商",
+  "settings.speech.separateProviders.subtitle": "为语音输入 (STT) 和语音输出 (TTS) 使用不同的 API 密钥和端点。",
+  "settings.speech.stt.section.title": "语音输入 (语音转文字)",
+  "settings.speech.tts.section.title": "语音输出 (文字转语音)",
+  "settings.speech.stt.apiKey.title": "输入 API 密钥",
+  "settings.speech.stt.apiKey.subtitle": "用于语音转文字请求。",
+  "settings.speech.stt.apiKey.placeholder": "输入新的输入 API 密钥",
+  "settings.speech.stt.apiKey.storedNote": "已保存的输入 API 密钥已隐藏。输入新值可替换，留空则保留当前密钥。",
+  "settings.speech.stt.apiKey.usingShared": "正在使用共享 API 密钥。输入新密钥可覆盖。",
+  "settings.speech.stt.apiKey.clearAction": "清除已保存的输入密钥",
+  "settings.speech.stt.apiKey.clearPending": "保存后将删除已保存的输入 API 密钥。",
+  "settings.speech.stt.baseUrl.title": "输入基础 URL",
+  "settings.speech.stt.baseUrl.subtitle": "用于语音转文字的 OpenAI 兼容端点。",
+  "settings.speech.stt.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.stt.model.title": "输入模型",
+  "settings.speech.stt.model.subtitle": "用于语音转文字的模型。",
+  "settings.speech.tts.apiKey.title": "输出 API 密钥",
+  "settings.speech.tts.apiKey.subtitle": "用于文字转语音请求。",
+  "settings.speech.tts.apiKey.placeholder": "输入新的输出 API 密钥",
+  "settings.speech.tts.apiKey.storedNote": "已保存的输出 API 密钥已隐藏。输入新值可替换，留空则保留当前密钥。",
+  "settings.speech.tts.apiKey.usingShared": "正在使用共享 API 密钥。输入新密钥可覆盖。",
+  "settings.speech.tts.apiKey.clearAction": "清除已保存的输出密钥",
+  "settings.speech.tts.apiKey.clearPending": "保存后将删除已保存的输出 API 密钥。",
+  "settings.speech.tts.baseUrl.title": "输出基础 URL",
+  "settings.speech.tts.baseUrl.subtitle": "用于文字转语音的 OpenAI 兼容端点。",
+  "settings.speech.tts.baseUrl.placeholder": "https://api.openai.com/v1",
+  "settings.speech.tts.model.title": "输出模型",
+  "settings.speech.tts.model.subtitle": "用于文字转语音的模型。",
   "settings.nav.sidecars": "SideCars",
   "settings.section.sidecars.eyebrow": "服务器服务",
   "settings.section.sidecars.title": "SideCars",
diff --git a/packages/ui/src/lib/keyboard.ts b/packages/ui/src/lib/keyboard.ts
index d4f1ddba..88cfe485 100644
--- a/packages/ui/src/lib/keyboard.ts
+++ b/packages/ui/src/lib/keyboard.ts
@@ -1,6 +1,6 @@
 import { activeInstanceId } from "../stores/instances"
 import { selectAppTabByIndex } from "../stores/app-tabs"
-import { activeSessionId, setActiveSession, getSessions, activeParentSessionId } from "../stores/sessions"
+import { activeSessionId, setActiveSession, getSessionFamily, activeParentSessionId } from "../stores/sessions"
 import { keyboardRegistry } from "./keyboard-registry"
 import { isMac } from "./keyboard-utils"
 
@@ -48,8 +48,7 @@ export function setupTabKeyboardShortcuts(
       const parentId = activeParentSessionId().get(instanceId)
       if (!parentId) return
 
-      const sessions = getSessions(instanceId)
-      const sessionFamily = sessions.filter((s) => s.id === parentId || s.parentId === parentId)
+      const sessionFamily = getSessionFamily(instanceId, parentId)
       const allTabs = sessionFamily.map((s) => s.id).concat(["logs"])
 
       if (allTabs[index]) {
diff --git a/packages/ui/src/lib/markdown.test.ts b/packages/ui/src/lib/markdown.test.ts
new file mode 100644
index 00000000..03d4497c
--- /dev/null
+++ b/packages/ui/src/lib/markdown.test.ts
@@ -0,0 +1,114 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { renderMarkdown } from "./markdown"
+
+describe("renderMarkdown bracket math delimiters", () => {
+  it("renders inline bracket math", async () => {
+    const html = await renderMarkdown(String.raw`\(x^2\)`, { suppressHighlight: true })
+
+    assert.match(html, /<span class="katex">/)
+    assert.match(html, /x/)
+  })
+
+  it("renders multiline display bracket math", async () => {
+    const html = await renderMarkdown(String.raw`\[x^
+2\]`, { suppressHighlight: true })
+
+    assert.match(html, /<span class="katex-display">/)
+  })
+
+  it("splits prose around adjacent single-line and multiline display math", async () => {
+    const singleLine = await renderMarkdown("before\n\\[x^2\\]\nafter", { suppressHighlight: true })
+    const multiline = await renderMarkdown("before\n\\[\nx^2\n\\]\nafter", { suppressHighlight: true })
+
+    for (const html of [singleLine, multiline]) {
+      assert.match(html, /^<p>before<\/p>\n<span class="katex-display">/)
+      assert.match(html, /<p>after<\/p>\n$/)
+      assert.doesNotMatch(html, /<br>/)
+      assert.doesNotMatch(html, /katex-error/)
+    }
+  })
+
+  it("preserves dollar-delimited math", async () => {
+    const inline = await renderMarkdown("$x^2$", { suppressHighlight: true })
+    const display = await renderMarkdown("$$x^2$$", { suppressHighlight: true })
+
+    assert.match(inline, /<span class="katex">/)
+    assert.match(display, /<span class="katex-display">/)
+  })
+
+  it("leaves bracket delimiters literal in code", async () => {
+    const inline = await renderMarkdown("`\\(x^2\\)`", { suppressHighlight: true })
+    const fenced = await renderMarkdown("```text\n\\[x^2\\]\n```", { suppressHighlight: true })
+
+    assert.doesNotMatch(inline, /class="katex/)
+    assert.match(inline, /\\\(x\^2\\\)/)
+    assert.doesNotMatch(fenced, /class="katex/)
+    assert.match(fenced, /\\\[x\^2\\\]/)
+  })
+
+  it("does not split incomplete or empty display delimiters", async () => {
+    const empty = await renderMarkdown(String.raw`a \[\] b`, { suppressHighlight: true })
+    const unmatched = await renderMarkdown(String.raw`a \[x`, { suppressHighlight: true })
+
+    assert.equal(empty, "<p>a [] b</p>\n")
+    assert.equal(unmatched, "<p>a [x</p>\n")
+  })
+
+  it("does not hijack bracket delimiters in inline code or dollar math", async () => {
+    const code = await renderMarkdown("`\\[x\\]`", { suppressHighlight: true })
+    const multilineCode = await renderMarkdown("`a\n\\[x\\]`", { suppressHighlight: true })
+    const multilineDoubleCode = await renderMarkdown("``a\n\\[x\\]``", { suppressHighlight: true })
+    const escapedBackticks = await renderMarkdown("\\`a\n\\[x\\]\nafter\\`", { suppressHighlight: true })
+    const inlineDollar = await renderMarkdown(String.raw`$\[x\]$`, { suppressHighlight: true })
+    const displayDollar = await renderMarkdown(String.raw`$$\[x\]$$`, { suppressHighlight: true })
+
+    assert.equal(code, '<p><code class="inline-code">\\[x\\]</code></p>\n')
+    assert.equal(multilineCode, '<p><code class="inline-code">a \\[x\\]</code></p>\n')
+    assert.equal(multilineDoubleCode, '<p><code class="inline-code">a \\[x\\]</code></p>\n')
+    assert.match(escapedBackticks, /<span class="katex-display">/)
+    assert.doesNotMatch(escapedBackticks, /katex-error/)
+    assert.match(inlineDollar, /^<p><span class="katex-error"/)
+    assert.doesNotMatch(inlineDollar, /katex-display/)
+    assert.match(displayDollar, /^<p><span class="katex-error"/)
+  })
+
+  it("renders bracket display math after dollar display or bare dollars", async () => {
+    const afterDollarDisplay = await renderMarkdown("$$\nx\n$$\n\n\\[y\\]", { suppressHighlight: true })
+    const afterBareDollars = await renderMarkdown("plain $$\n\n\\[x\\]", { suppressHighlight: true })
+
+    assert.equal((afterDollarDisplay.match(/class="katex-display"/g) ?? []).length, 2)
+    assert.match(afterBareDollars, /class="katex-display"/)
+    assert.doesNotMatch(afterBareDollars, /<br>/)
+  })
+
+  it("leaves escaped, empty, and unmatched bracket delimiters literal", async () => {
+    const html = await renderMarkdown(String.raw`\\(x^2\) \\[x^2\] \(\) \[\] \(x^2 \[x^2`, {
+      suppressHighlight: true,
+    })
+
+    assert.doesNotMatch(html, /class="katex/)
+    assert.match(html, /\\\(x\^2\\\)/)
+    assert.match(html, /\\\[x\^2\]/)
+  })
+
+  it("leaves line-start and mid-paragraph invalid display delimiters literal", async () => {
+    const html = await renderMarkdown("\\\\[x\\]\n\\[\]\n\\[x\na \\[\] b\na \\[x", { suppressHighlight: true })
+
+    assert.doesNotMatch(html, /class="katex/)
+    assert.doesNotMatch(html, /katex-error/)
+  })
+
+  it("does not split paragraphs for whitespace-only display delimiters", async () => {
+    const singleLine = await renderMarkdown("before\n\\[   \\]\nafter", { suppressHighlight: true })
+    const multiline = await renderMarkdown("before\n\\[\n \t\n\\]\nafter", { suppressHighlight: true })
+
+    for (const html of [singleLine, multiline]) {
+      assert.doesNotMatch(html, /class="katex/)
+      assert.doesNotMatch(html, /katex-error/)
+      assert.match(html, /^<p>before<br>/)
+      assert.match(html, /after<\/p>\n$/)
+    }
+  })
+})
diff --git a/packages/ui/src/lib/markdown.ts b/packages/ui/src/lib/markdown.ts
index 70bec0a5..9d40506a 100644
--- a/packages/ui/src/lib/markdown.ts
+++ b/packages/ui/src/lib/markdown.ts
@@ -1,5 +1,6 @@
-import { marked } from "marked"
+import { marked, type Tokenizer, type Tokens } from "marked"
 import markedKatex from "marked-katex-extension"
+import katex from "katex"
 import { getLogger } from "./logger"
 import { tGlobal } from "./i18n"
 import type { Highlighter } from "shiki/bundle/full"
@@ -13,14 +14,42 @@ let currentTheme: "light" | "dark" = "light"
 let isInitialized = false
 let highlightSuppressed = false
 let escapeRawHtmlEnabled = false
+let defaultCodeBlockWrapEnabled = true
 let rendererSetup = false
 let shikiModulePromise: Promise<typeof import("shiki/bundle/full")> | null = null
 let bundledLanguagesCache: typeof import("shiki/bundle/full")["bundledLanguages"] | null = null
+const codeBlockRenderOccurrences = new Map<string, number>()
 
-// Math rendering is handled by marked-katex-extension (registered in setupRenderer).
-// Delimiter rules, boundaries, CJK punctuation, and block/inline rendering are
-// all delegated to the maintained extension so we avoid ~200 lines of fragile
-// hand-rolled tokenizer code.
+// Dollar-delimited math is handled by marked-katex-extension; bracket delimiters
+// use the small parser-native rules registered in setupRenderer.
+
+const BRACKET_DISPLAY_MATH_RULE = /^\\\[([\s\S]+?)\\\]/
+
+// Find a complete line-start display delimiter while skipping inline code spans.
+function findBracketDisplayStart(src: string): number {
+  const codeRule = marked.Lexer.rules.inline.gfm.code
+  let index = 0
+
+  while (index < src.length) {
+    const code = codeRule.exec(src.slice(index))
+    let precedingBackslashes = 0
+    for (let cursor = index - 1; src[cursor] === "\\"; cursor--) {
+      precedingBackslashes++
+    }
+    if (code?.index === 0 && precedingBackslashes % 2 === 0) {
+      index += code[0].length
+      continue
+    }
+
+    const bracketMath = BRACKET_DISPLAY_MATH_RULE.exec(src.slice(index))
+    if ((index === 0 || src[index - 1] === "\n") && bracketMath?.[1].trim()) {
+      return index
+    }
+    index++
+  }
+
+  return -1
+}
 
 const ALLOWED_RAW_HTML_TAGS = new Set([
   "a",
@@ -151,6 +180,19 @@ function sanitizeRawHtmlFragment(html: string): string {
   return template.innerHTML
 }
 
+function hashString(value: string): string {
+  let hash = 2166136261
+  for (let index = 0; index < value.length; index++) {
+    hash ^= value.charCodeAt(index)
+    hash = Math.imul(hash, 16777619)
+  }
+  return (hash >>> 0).toString(16)
+}
+
+function resetCodeBlockRenderState() {
+  codeBlockRenderOccurrences.clear()
+}
+
 // Track loaded languages and queue for on-demand loading
 const loadedLanguages = new Set<string>()
 const queuedLanguages = new Set<string>()
@@ -386,6 +428,92 @@ function setupRenderer(isDark: boolean) {
     strict: "ignore",
   }))
 
+  marked.use({
+    extensions: [
+      {
+        name: "inlineBracketMath",
+        level: "inline",
+        // Find unescaped inline bracket math without scanning beyond the next line.
+        start(src: string) {
+          return src.search(/(?<!\\)\\\(/)
+        },
+        // Tokenize non-empty inline math delimited by \( and \).
+        tokenizer(src: string) {
+          const escaped = /^\\\\\(([^\n]+?)\\\)/.exec(src)
+          if (escaped) {
+            return {
+              type: "inlineBracketMath",
+              raw: escaped[0],
+              text: escaped[0],
+              escaped: true,
+            }
+          }
+
+          const match = /^\\\(([^\n]+?)\\\)/.exec(src)
+          if (!match) return
+
+          return {
+            type: "inlineBracketMath",
+            raw: match[0],
+            text: match[1],
+          }
+        },
+        // Render inline bracket math with the existing KaTeX error policy.
+        renderer(token: Tokens.Generic) {
+          if (token.escaped) return escapeHtml(token.raw)
+
+          return katex.renderToString(token.text, {
+            throwOnError: false,
+            strict: "ignore",
+            displayMode: false,
+          })
+        },
+      },
+      {
+        name: "blockBracketMath",
+        level: "block",
+        // Tokenize non-empty display math delimited by \[ and \], across lines.
+        tokenizer(src: string) {
+          const match = BRACKET_DISPLAY_MATH_RULE.exec(src)
+          if (!match || !match[1].trim()) return
+
+          return {
+            type: "blockBracketMath",
+            raw: match[0],
+            text: match[1],
+          }
+        },
+        // Render display bracket math with the existing KaTeX error policy.
+        renderer(token: Tokens.Generic) {
+          return katex.renderToString(token.text, {
+            throwOnError: false,
+            strict: "ignore",
+            displayMode: true,
+          })
+        },
+      },
+    ],
+    tokenizer: {
+      // Split a paragraph before a valid display delimiter so the block lexer can consume it.
+      paragraph(this: Tokenizer, src: string) {
+        const cap = this.rules.block.paragraph.exec(src)
+        if (!cap) return false
+
+        const bracketStart = findBracketDisplayStart(cap[0])
+        if (bracketStart <= 0) return false
+
+        const raw = cap[0].slice(0, bracketStart)
+        const text = raw.endsWith("\n") ? raw.slice(0, -1) : raw
+        return {
+          type: "paragraph",
+          raw,
+          text,
+          tokens: this.lexer.inline(text),
+        }
+      },
+    },
+  })
+
   const renderer = new marked.Renderer()
 
   renderer.code = (code: string, lang: string | undefined) => {
@@ -394,29 +522,50 @@ function setupRenderer(isDark: boolean) {
 
     // Use "text" as default when no language is specified
     const resolvedLang = lang && lang.trim() ? lang.trim() : "text"
+    const occurrenceBaseKey = `${resolvedLang}\u0000${decodedCode}`
+    const occurrence = codeBlockRenderOccurrences.get(occurrenceBaseKey) ?? 0
+    codeBlockRenderOccurrences.set(occurrenceBaseKey, occurrence + 1)
+    const codeBlockKey = hashString(`${occurrenceBaseKey}\u0000${occurrence}`)
     const escapedLang = escapeHtml(resolvedLang)
     const copyLabel = escapeHtml(tGlobal("markdown.copy"))
+    const defaultWrapEnabled = defaultCodeBlockWrapEnabled
+    const wrapLabel = escapeHtml(tGlobal(defaultWrapEnabled ? "markdown.codeBlock.wrap.disable" : "markdown.codeBlock.wrap.enable"))
+    const wrapActiveClass = defaultWrapEnabled ? " active" : ""
+    const wrapPressed = defaultWrapEnabled ? "true" : "false"
 
     const header = `
  <div class="code-block-header">
    <span class="code-block-language">${escapedLang}</span>
-   <button class="code-block-copy" data-code="${encodedCode}">
-    <svg class="copy-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-      <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
-      <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
-     </svg>
-    <span class="copy-text">${copyLabel}</span>
-   </button>
- </div>
- `.trim()
+   <span class="code-block-actions">
+    <button type="button" class="code-block-wrap${wrapActiveClass}" data-code-block-key="${codeBlockKey}" aria-pressed="${wrapPressed}" aria-label="${wrapLabel}" title="${wrapLabel}">
+     <svg class="wrap-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+       <path d="M3 6h18"></path>
+       <path d="M3 12h15a3 3 0 1 1 0 6h-4"></path>
+       <path d="m16 16-2 2 2 2"></path>
+       <path d="M3 18h7"></path>
+      </svg>
+     <span class="wrap-text">${wrapLabel}</span>
+    </button>
+    <button type="button" class="code-block-copy" data-code="${encodedCode}">
+     <svg class="copy-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+       <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+       <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+      </svg>
+     <span class="copy-text">${copyLabel}</span>
+    </button>
+   </span>
+  </div>
+  `.trim()
+
+    const renderCodeBlock = (body: string) => `<div class="markdown-code-block" data-language="${escapedLang}" data-code="${encodedCode}" data-code-block-key="${codeBlockKey}" data-wrap-lines="${defaultWrapEnabled ? "true" : "false"}">${header}${body}</div>`
 
     if (highlightSuppressed) {
-      return `<div class="markdown-code-block" data-language="${escapedLang}" data-code="${encodedCode}">${header}<pre><code class="language-${escapedLang}">${escapeHtml(decodedCode)}</code></pre></div>`
+      return renderCodeBlock(`<pre><code class="language-${escapedLang}">${escapeHtml(decodedCode)}</code></pre>`)
     }
 
     // Skip highlighting for "text" language or when highlighter is not available
     if (resolvedLang === "text" || !highlighter) {
-      return `<div class="markdown-code-block" data-language="${escapedLang}" data-code="${encodedCode}">${header}<pre><code>${escapeHtml(decodedCode)}</code></pre></div>`
+      return renderCodeBlock(`<pre><code>${escapeHtml(decodedCode)}</code></pre>`)
     }
 
     // Resolve language and check if it's loaded
@@ -425,23 +574,23 @@ function setupRenderer(isDark: boolean) {
 
     // Skip highlighting for "text" aliases
     if (langKey === "text" || raw === "text") {
-      return `<div class="markdown-code-block" data-language="${escapedLang}" data-code="${encodedCode}">${header}<pre><code class="language-${escapedLang}">${escapeHtml(decodedCode)}</code></pre></div>`
+      return renderCodeBlock(`<pre><code class="language-${escapedLang}">${escapeHtml(decodedCode)}</code></pre>`)
     }
 
     // Use highlighting if language is loaded, otherwise fall back to plain code
     if (loadedLanguages.has(langKey)) {
       try {
-         const html = highlighter!.codeToHtml(decodedCode, {
-           lang: langKey,
-           theme: currentTheme === "dark" ? "github-dark" : "github-light-high-contrast",
-         })
-        return `<div class="markdown-code-block" data-language="${escapedLang}" data-code="${encodedCode}">${header}${html}</div>`
+        const html = highlighter!.codeToHtml(decodedCode, {
+          lang: langKey,
+          theme: currentTheme === "dark" ? "github-dark" : "github-light-high-contrast",
+        })
+        return renderCodeBlock(html)
       } catch {
         // Fall through to plain code if highlighting fails
       }
     }
 
-    return `<div class="markdown-code-block" data-language="${escapedLang}" data-code="${encodedCode}">${header}<pre><code class="language-${escapedLang}">${escapeHtml(decodedCode)}</code></pre></div>`
+    return renderCodeBlock(`<pre><code class="language-${escapedLang}">${escapeHtml(decodedCode)}</code></pre>`)
   }
 
   renderer.link = (href: string, title: string | null | undefined, text: string) => {
@@ -486,6 +635,7 @@ export async function renderMarkdown(
   options?: {
     suppressHighlight?: boolean
     escapeRawHtml?: boolean
+    defaultCodeBlockWrap?: boolean
   },
 ): Promise<string> {
   if (!isInitialized) {
@@ -495,6 +645,7 @@ export async function renderMarkdown(
 
   const suppressHighlight = options?.suppressHighlight ?? false
   const escapeRawHtml = options?.escapeRawHtml ?? false
+  const defaultCodeBlockWrap = options?.defaultCodeBlockWrap ?? true
   const decoded = decodeHtmlEntities(content)
 
   if (!suppressHighlight) {
@@ -504,15 +655,20 @@ export async function renderMarkdown(
 
   const previousSuppressed = highlightSuppressed
   const previousEscapeRawHtml = escapeRawHtmlEnabled
+  const previousDefaultCodeBlockWrap = defaultCodeBlockWrapEnabled
   highlightSuppressed = suppressHighlight
   escapeRawHtmlEnabled = escapeRawHtml
+  defaultCodeBlockWrapEnabled = defaultCodeBlockWrap
 
   try {
     // Proceed to parse immediately - highlighting will be available on next render
+    resetCodeBlockRenderState()
     return marked.parse(decoded) as Promise<string>
   } finally {
+    resetCodeBlockRenderState()
     highlightSuppressed = previousSuppressed
     escapeRawHtmlEnabled = previousEscapeRawHtml
+    defaultCodeBlockWrapEnabled = previousDefaultCodeBlockWrap
   }
 }
 
diff --git a/packages/ui/src/lib/message-selection-position.test.ts b/packages/ui/src/lib/message-selection-position.test.ts
new file mode 100644
index 00000000..daacf637
--- /dev/null
+++ b/packages/ui/src/lib/message-selection-position.test.ts
@@ -0,0 +1,29 @@
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { getMessageSelectionActionPosition } from "./message-selection-position.ts"
+
+test("places touch selection actions below the final line while desktop stays above", () => {
+  const rects = [
+    { top: 180, bottom: 200, left: 120 },
+    { top: 220, bottom: 240, left: 80 },
+  ]
+  const shell = { top: 100, left: 20 }
+
+  assert.deepEqual(getMessageSelectionActionPosition(rects, rects[0]!, shell, 400, 300, false), {
+    top: 40,
+    left: 100,
+  })
+  assert.deepEqual(getMessageSelectionActionPosition(rects, rects[0]!, shell, 400, 300, true), {
+    top: 172,
+    left: 60,
+  })
+})
+
+test("keeps touch selection actions visible near the bottom edge", () => {
+  const rect = { top: 340, bottom: 360, left: 80 }
+
+  assert.deepEqual(
+    getMessageSelectionActionPosition([rect], rect, { top: 100, left: 20 }, 400, 300, true),
+    { top: 8, left: 60 },
+  )
+})
diff --git a/packages/ui/src/lib/message-selection-position.ts b/packages/ui/src/lib/message-selection-position.ts
new file mode 100644
index 00000000..14bbeba9
--- /dev/null
+++ b/packages/ui/src/lib/message-selection-position.ts
@@ -0,0 +1,39 @@
+interface SelectionRect {
+  top: number
+  bottom: number
+  left: number
+}
+
+interface SelectionShellRect {
+  top: number
+  left: number
+}
+
+const EDGE_GAP_PX = 8
+const DESKTOP_OFFSET_PX = 40
+const MOBILE_HANDLE_GAP_PX = 32
+const POPOVER_HEIGHT_PX = 40
+const POPOVER_WIDTH_PX = 260
+
+export function getMessageSelectionActionPosition(
+  selectionRects: readonly SelectionRect[],
+  fallbackRect: SelectionRect,
+  shellRect: SelectionShellRect,
+  shellWidth: number,
+  shellHeight: number,
+  placeBelowSelection: boolean,
+): { top: number; left: number } {
+  const anchor = selectionRects.length
+    ? selectionRects[placeBelowSelection ? selectionRects.length - 1 : 0]!
+    : fallbackRect
+  const belowTop = anchor.bottom - shellRect.top + MOBILE_HANDLE_GAP_PX
+  const top = placeBelowSelection
+    ? belowTop <= shellHeight - POPOVER_HEIGHT_PX - EDGE_GAP_PX ? belowTop : EDGE_GAP_PX
+    : anchor.top - shellRect.top - DESKTOP_OFFSET_PX
+  const maxLeft = Math.max(shellWidth - POPOVER_WIDTH_PX, EDGE_GAP_PX)
+
+  return {
+    top: Math.max(top, EDGE_GAP_PX),
+    left: Math.min(Math.max(anchor.left - shellRect.left, EDGE_GAP_PX), maxLeft),
+  }
+}
diff --git a/packages/ui/src/lib/native/client-state.ts b/packages/ui/src/lib/native/client-state.ts
new file mode 100644
index 00000000..7b6fc1e3
--- /dev/null
+++ b/packages/ui/src/lib/native/client-state.ts
@@ -0,0 +1,58 @@
+import { invoke } from "@tauri-apps/api/core"
+import { isElectronHost, isLocalWindow, isTauriHost } from "../runtime-env"
+const LEGACY_WEB_KEYS = ["codenomad-client-snapshot-v1", "codenomad-client-restore-enabled-v1"]
+export type NativeClientStateLoadResult = {
+  isPrimary: boolean
+  restoreEnabled: boolean
+  snapshot: unknown | null
+}
+const SECONDARY_CLIENT_STATE: NativeClientStateLoadResult = { isPrimary: false, restoreEnabled: false, snapshot: null }
+const accessToken = (() => {
+  const bytes = new Uint8Array(32)
+  globalThis.crypto.getRandomValues(bytes)
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")
+})()
+let nativeAccessClaimed = false
+const electronApi = () => (window as Window & { electronAPI?: ElectronAPI }).electronAPI
+function dispatchNative<T>(electronOperation: (api: ElectronAPI | undefined) => Promise<T> | undefined, command: string, args: Record<string, unknown> = {}): Promise<T> | undefined {
+  if (isElectronHost()) return electronOperation(electronApi())
+  if (isTauriHost()) return invoke<T>(command, { accessToken, ...args })
+}
+async function claimNativeClientStateAccess(): Promise<boolean> {
+  if (!isLocalWindow()) return false
+  try {
+    const result = await dispatchNative<boolean | void>((api) => api?.claimClientStateAccess?.(accessToken), "client_state_claim_access")
+    nativeAccessClaimed = isTauriHost() || result === true
+  } catch {
+    nativeAccessClaimed = false
+  }
+  return nativeAccessClaimed
+}
+export async function loadNativeClientState(): Promise<NativeClientStateLoadResult> {
+  if (isElectronHost() || isTauriHost()) {
+    if (!await claimNativeClientStateAccess()) return SECONDARY_CLIENT_STATE
+    return await dispatchNative((api) => api?.loadClientState?.(accessToken), "client_state_load") ?? SECONDARY_CLIENT_STATE
+  }
+  try {
+    for (const key of LEGACY_WEB_KEYS) window.localStorage.removeItem(key)
+  } catch {}
+  return SECONDARY_CLIENT_STATE
+}
+async function mutateNativeClientState(electronOperation: (api: ElectronAPI) => Promise<boolean> | undefined, command: string, args: Record<string, unknown> = {}): Promise<boolean> {
+  if (!nativeAccessClaimed) return false
+  return await dispatchNative((api) => api && electronOperation(api), command, args) ?? false
+}
+export const saveNativeClientState = (snapshot: unknown): Promise<boolean> =>
+  mutateNativeClientState((api) => api.saveClientState?.(accessToken, snapshot), "client_state_save", { snapshot })
+export const setNativeRestoreEnabled = (enabled: boolean): Promise<boolean> =>
+  mutateNativeClientState((api) => api.setClientStateRestoreEnabled?.(accessToken, enabled), "client_state_set_restore_enabled", { enabled })
+export const clearNativeClientState = (): Promise<boolean> =>
+  mutateNativeClientState((api) => api.clearClientState?.(accessToken), "client_state_clear")
+function acknowledge(command: string, args: Record<string, unknown> = {}): Promise<void> {
+  if (!isTauriHost() || !nativeAccessClaimed) return Promise.resolve()
+  return invoke(command, { accessToken, ...args })
+}
+export const acknowledgeNativeClientStateNavigationFlush = (generation: number) =>
+  acknowledge("client_state_navigation_flushed", { generation })
+export const acknowledgeNativeClientStateRendererFlush = (generation: number) =>
+  acknowledge("client_state_renderer_flushed", { generation })
diff --git a/packages/ui/src/lib/native/desktop-events.test.ts b/packages/ui/src/lib/native/desktop-events.test.ts
index c414b04b..c6d0e388 100644
--- a/packages/ui/src/lib/native/desktop-events.test.ts
+++ b/packages/ui/src/lib/native/desktop-events.test.ts
@@ -1,6 +1,10 @@
 import assert from "node:assert/strict"
 import { describe, it } from "node:test"
-import { createTerminalErrorNotifier } from "./desktop-events.ts"
+import {
+  connectTauriWorkspaceEvents,
+  createTerminalErrorNotifier,
+  mapDesktopEventTransportStatus,
+} from "./desktop-events.ts"
 
 describe("createTerminalErrorNotifier", () => {
   it("calls onError once for repeated terminal notifications", () => {
@@ -17,3 +21,78 @@ describe("createTerminalErrorNotifier", () => {
     assert.equal(errors, 1)
   })
 })
+
+describe("mapDesktopEventTransportStatus", () => {
+  it("maps native connected state to shared connected state", () => {
+    assert.equal(mapDesktopEventTransportStatus("connected"), "connected")
+  })
+
+  it("maps native connecting state to shared connecting state", () => {
+    assert.equal(mapDesktopEventTransportStatus("connecting"), "connecting")
+  })
+
+  it("maps native transient failures to shared disconnected state", () => {
+    assert.equal(mapDesktopEventTransportStatus("disconnected"), "disconnected")
+    assert.equal(mapDesktopEventTransportStatus("error"), "disconnected")
+    assert.equal(mapDesktopEventTransportStatus("unauthorized"), "disconnected")
+  })
+})
+
+describe("connectTauriWorkspaceEvents", () => {
+  it("marks the transport connected when a batch opens the native stream", async () => {
+    let batchHandler: ((event: { payload: any }) => void) | undefined
+    const unlistened: string[] = []
+    const bridge = {
+      invoke: async (command: string) => {
+        if (command === "desktop_events_start") {
+          return { started: true, generation: 1 }
+        }
+        if (command === "desktop_events_stop") {
+          return undefined
+        }
+        throw new Error(`Unexpected command: ${command}`)
+      },
+      listen: async (eventName: string, handler: (event: { payload: any }) => void) => {
+        if (eventName === "desktop:event-batch") {
+          batchHandler = handler
+        }
+        return () => {
+          unlistened.push(eventName)
+        }
+      },
+    } as any
+
+    const statuses: string[] = []
+    const batches: unknown[] = []
+    let opens = 0
+
+    const connection = await connectTauriWorkspaceEvents(
+      {
+        onBatch: (events) => batches.push(events),
+        onOpen: () => {
+          opens += 1
+        },
+        onStatus: (status) => statuses.push(status),
+      },
+      { reconnect: {} },
+      bridge,
+    )
+
+    assert.ok(batchHandler)
+    batchHandler({
+      payload: {
+        generation: 1,
+        sequence: 1,
+        emittedAt: Date.now(),
+        events: [{ type: "server.heartbeat" }],
+      },
+    })
+
+    assert.deepEqual(statuses, ["connected"])
+    assert.equal(opens, 1)
+    assert.equal(batches.length, 1)
+
+    connection.disconnect()
+    assert.deepEqual(unlistened, ["desktop:event-batch", "desktop:event-stream-status"])
+  })
+})
diff --git a/packages/ui/src/lib/native/desktop-events.ts b/packages/ui/src/lib/native/desktop-events.ts
index 01c9af6e..2ee51d4c 100644
--- a/packages/ui/src/lib/native/desktop-events.ts
+++ b/packages/ui/src/lib/native/desktop-events.ts
@@ -4,9 +4,14 @@ import type { WorkspaceEventPayload } from "../../../../server/src/api-types"
 import type {
   DesktopEventsStartResult,
   DesktopEventTransportStartOptions,
+  DesktopEventTransportState,
   DesktopEventTransportStatusPayload,
 } from "../event-transport-contract"
-import type { WorkspaceEventConnection, WorkspaceEventTransportCallbacks } from "../event-transport"
+import type {
+  WorkspaceEventConnection,
+  WorkspaceEventTransportCallbacks,
+  WorkspaceEventTransportStatus,
+} from "../event-transport"
 import { getLogger } from "../logger"
 
 const log = getLogger("sse")
@@ -18,6 +23,16 @@ interface WorkspaceEventBatchPayload {
   events: WorkspaceEventPayload[]
 }
 
+interface DesktopEventTransportBridge {
+  invoke: typeof invoke
+  listen: typeof listen
+}
+
+const defaultDesktopEventTransportBridge: DesktopEventTransportBridge = {
+  invoke,
+  listen,
+}
+
 export function createTerminalErrorNotifier(callbacks: Pick<WorkspaceEventTransportCallbacks, "onError">) {
   let raised = false
   return () => {
@@ -27,9 +42,18 @@ export function createTerminalErrorNotifier(callbacks: Pick<WorkspaceEventTransp
   }
 }
 
+export function mapDesktopEventTransportStatus(
+  state: DesktopEventTransportState,
+): WorkspaceEventTransportStatus {
+  if (state === "connected") return "connected"
+  if (state === "connecting") return "connecting"
+  return "disconnected"
+}
+
 export async function connectTauriWorkspaceEvents(
   callbacks: WorkspaceEventTransportCallbacks,
   options: DesktopEventTransportStartOptions,
+  bridge: DesktopEventTransportBridge = defaultDesktopEventTransportBridge,
 ): Promise<WorkspaceEventConnection> {
   let closed = false
   let opened = false
@@ -45,6 +69,7 @@ export async function connectTauriWorkspaceEvents(
 
     if (!opened) {
       opened = true
+      callbacks.onStatus?.("connected")
       callbacks.onOpen?.()
     }
 
@@ -59,6 +84,8 @@ export async function connectTauriWorkspaceEvents(
   const handleStatusPayload = (payload: DesktopEventTransportStatusPayload) => {
     if (!payload || !matchesGeneration(payload.generation)) return
 
+    callbacks.onStatus?.(mapDesktopEventTransportStatus(payload.state))
+
     if (payload.state === "connected" && !opened) {
       opened = true
       callbacks.onOpen?.()
@@ -107,7 +134,7 @@ export async function connectTauriWorkspaceEvents(
     }
   }
 
-  const unlistenBatch = await listen<WorkspaceEventBatchPayload>("desktop:event-batch", (event) => {
+  const unlistenBatch = await bridge.listen<WorkspaceEventBatchPayload>("desktop:event-batch", (event) => {
     if (closed) return
     const payload = event.payload
     if (!payload) return
@@ -118,7 +145,7 @@ export async function connectTauriWorkspaceEvents(
     handleBatchPayload(payload)
   })
 
-  const unlistenStatus = await listen<DesktopEventTransportStatusPayload>("desktop:event-stream-status", (event) => {
+  const unlistenStatus = await bridge.listen<DesktopEventTransportStatusPayload>("desktop:event-stream-status", (event) => {
     if (closed) return
     const payload = event.payload
     if (!payload) return
@@ -130,7 +157,7 @@ export async function connectTauriWorkspaceEvents(
   })
 
   try {
-    const result = await invoke<DesktopEventsStartResult>("desktop_events_start", { request: options })
+    const result = await bridge.invoke<DesktopEventsStartResult>("desktop_events_start", { request: options })
     if (!result?.started) {
       throw new Error(result?.reason ?? "desktop event transport unavailable")
     }
@@ -151,7 +178,7 @@ export async function connectTauriWorkspaceEvents(
       closed = true
       unlistenBatch()
       unlistenStatus()
-      void invoke("desktop_events_stop").catch((error) => {
+      void bridge.invoke("desktop_events_stop").catch((error) => {
         log.warn("Failed to stop native desktop event transport", error)
       })
     },
diff --git a/packages/ui/src/lib/notifications.tsx b/packages/ui/src/lib/notifications.tsx
index 4102dd8e..45ab07a9 100644
--- a/packages/ui/src/lib/notifications.tsx
+++ b/packages/ui/src/lib/notifications.tsx
@@ -11,16 +11,19 @@ export type ToastHandle = {
 
 type ToastPosition = "top-left" | "top-right" | "top-center" | "bottom-left" | "bottom-right" | "bottom-center"
 
+export type ToastAction = {
+  label: string
+  href: string
+  onClick?: () => void | Promise<void>
+}
+
 export type ToastPayload = {
   title?: string
   message: string
   variant: ToastVariant
   duration?: number
   position?: ToastPosition
-  action?: {
-    label: string
-    href: string
-  }
+  action?: ToastAction
 }
 
 // ==================== Toast History Types ====================
@@ -42,10 +45,7 @@ export interface IToastHistoryItem {
   /** Read state (clicked) */
   read: boolean;
   /** Action link (optional) */
-  action?: {
-    label: string;
-    href: string;
-  };
+  action?: ToastAction;
 }
 
 /**
@@ -297,6 +297,20 @@ async function openExternalUrl(url: string): Promise<void> {
   }
 }
 
+export async function runToastAction(action: ToastAction): Promise<void> {
+  if (!action.onClick) {
+    await openExternalUrl(action.href)
+    return
+  }
+
+  try {
+    await action.onClick()
+  } catch (error) {
+    console.warn("[notifications] action failed; opening fallback link", error)
+    await openExternalUrl(action.href)
+  }
+}
+
 // ==================== Variant Accent Styles ====================
 
 const variantAccent: Record<
@@ -381,7 +395,7 @@ export function showToastNotification(payload: ToastPayload): ToastHandle {
               <button
                 type="button"
                 class="mt-3 inline-flex items-center text-xs font-semibold uppercase tracking-wide text-sky-300 hover:text-sky-200"
-                onClick={() => void openExternalUrl(payload.action!.href)}
+                onClick={() => void runToastAction(payload.action!)}
               >
                 {payload.action.label}
               </button>
diff --git a/packages/ui/src/lib/opencode-api.test.ts b/packages/ui/src/lib/opencode-api.test.ts
new file mode 100644
index 00000000..0897e435
--- /dev/null
+++ b/packages/ui/src/lib/opencode-api.test.ts
@@ -0,0 +1,40 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { getOpencodeErrorMessage } from "./opencode-api.ts"
+
+describe("getOpencodeErrorMessage", () => {
+  it("uses the detailed message from a nested SDK error", () => {
+    const error = new Error("session.list failed")
+    ;(error as Error & { cause: unknown }).cause = {
+      data: { message: 'Expected DateTime.Utc at ["items"][37]["time"]["archived"]' },
+    }
+
+    assert.equal(
+      getOpencodeErrorMessage(error, "Unable to load sessions"),
+      'Expected DateTime.Utc at ["items"][37]["time"]["archived"]',
+    )
+  })
+
+  it("uses the contextual fallback when no detail is available", () => {
+    assert.equal(getOpencodeErrorMessage({}, "Unable to load sessions"), "Unable to load sessions")
+  })
+
+  it("keeps a useful outer message when the cause has no detail", () => {
+    const error = new Error("Network request failed")
+    ;(error as Error & { cause: unknown }).cause = { code: "ECONNRESET" }
+    assert.equal(getOpencodeErrorMessage(error, "Unable to load sessions"), "Network request failed")
+  })
+
+  it("reads structured response bodies and handles cyclic causes", () => {
+    assert.equal(
+      getOpencodeErrorMessage({ body: { message: "Invalid session timestamp" } }, "Unable to load sessions"),
+      "Invalid session timestamp",
+    )
+
+    const first: { cause?: unknown } = {}
+    const second: { cause?: unknown } = { cause: first }
+    first.cause = second
+    assert.equal(getOpencodeErrorMessage(first, "Unable to load sessions"), "Unable to load sessions")
+  })
+})
diff --git a/packages/ui/src/lib/opencode-api.ts b/packages/ui/src/lib/opencode-api.ts
index 58c4f24a..70bbd73d 100644
--- a/packages/ui/src/lib/opencode-api.ts
+++ b/packages/ui/src/lib/opencode-api.ts
@@ -10,6 +10,29 @@ export class OpencodeApiError extends Error {
   }
 }
 
+export function getOpencodeErrorMessage(error: unknown, fallback: string): string {
+  const seen = new Set<unknown>()
+
+  const extract = (value: unknown): string | undefined => {
+    if (typeof value === "string") return value.trim() || undefined
+    if (!value || typeof value !== "object" || seen.has(value)) return undefined
+    seen.add(value)
+
+    const candidate = value as any
+    const direct = [candidate.data?.message, candidate.body?.message, candidate.error]
+      .find((item) => typeof item === "string" && item.trim())
+    if (direct) return direct.trim()
+
+    const nested = extract(candidate.cause) ?? extract(candidate.error) ?? extract(candidate.body)
+    if (nested) return nested
+
+    if (typeof candidate.message === "string" && candidate.message.trim()) return candidate.message.trim()
+    return undefined
+  }
+
+  return extract(error) ?? fallback
+}
+
 type RequestResultLike<T> =
   | {
       data: T
diff --git a/packages/ui/src/lib/prompt-display-metadata.ts b/packages/ui/src/lib/prompt-display-metadata.ts
index 395f9da8..9f1fa46c 100644
--- a/packages/ui/src/lib/prompt-display-metadata.ts
+++ b/packages/ui/src/lib/prompt-display-metadata.ts
@@ -1,4 +1,5 @@
 import type { Attachment, FileSource, TextSource } from "../types/attachment"
+import { createAttachmentPlaceholderRegex } from "./attachment-placeholders"
 
 export type PromptDisplaySegmentKind = "inline" | "pasted"
 
@@ -21,15 +22,12 @@ export interface PreparedPromptDisplayText {
   displayMetadata?: PromptDisplayMetadata
 }
 
-const PASTED_PLACEHOLDER_REGEX = /\[\s*pasted\s*#\s*(\d+)\s*\]/gi
-
 function normalizeLineEndings(text: string): string {
   return text.replace(/\r\n?/g, "\n")
 }
 
 function hasPastedPlaceholders(text: string): boolean {
-  PASTED_PLACEHOLDER_REGEX.lastIndex = 0
-  return PASTED_PLACEHOLDER_REGEX.test(text)
+  return createAttachmentPlaceholderRegex("pasted").test(text)
 }
 
 function pushInlineSegment(segments: PromptDisplaySegment[], text: string): void {
@@ -120,7 +118,7 @@ export function resolvePastedPlaceholders(prompt: string, attachments: Attachmen
     return result
   }
 
-  return result.replace(PASTED_PLACEHOLDER_REGEX, (fullMatch, counter: string) => {
+  return result.replace(createAttachmentPlaceholderRegex("pasted"), (fullMatch, counter: string) => {
     const replacement = lookup.get(counter)
     return typeof replacement === "string" ? replacement : fullMatch
   })
@@ -137,14 +135,12 @@ export function preparePromptDisplayText(prompt: string, attachments: Attachment
     return { promptToSend: resolvedBase }
   }
 
-  PASTED_PLACEHOLDER_REGEX.lastIndex = 0
-
   const segments: PromptDisplaySegment[] = []
   let lastIndex = 0
   let foundResolvablePlaceholder = false
   let failed = false
 
-  for (const match of resolvedBase.matchAll(PASTED_PLACEHOLDER_REGEX)) {
+  for (const match of resolvedBase.matchAll(createAttachmentPlaceholderRegex("pasted"))) {
     const start = match.index ?? 0
     const counter = match[1]
     const replacement = lookup.get(counter)
diff --git a/packages/ui/src/lib/retry-utils.ts b/packages/ui/src/lib/retry-utils.ts
index d644cbe9..54350105 100644
--- a/packages/ui/src/lib/retry-utils.ts
+++ b/packages/ui/src/lib/retry-utils.ts
@@ -5,6 +5,7 @@ interface RetryOptions {
   backoffMultiplier?: number
   timeoutMs?: number
   shouldRetry?: (error: Error, attempt: number) => boolean
+  wait?: (delayMs: number) => Promise<void>
 }
 
 export async function retryWithBackoff<T>(
@@ -18,6 +19,7 @@ export async function retryWithBackoff<T>(
     backoffMultiplier = 2,
     timeoutMs,
     shouldRetry = () => true,
+    wait = (delayMs: number) => new Promise((resolve) => setTimeout(resolve, delayMs)),
   } = options
 
   let lastError: Error | null = null
@@ -44,7 +46,7 @@ export async function retryWithBackoff<T>(
       lastError = err
 
       if (attempt < maxAttempts && shouldRetry(err, attempt)) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs))
+        await wait(delayMs)
         delayMs = Math.min(delayMs * backoffMultiplier, maxDelayMs)
       } else {
         throw err
diff --git a/packages/ui/src/lib/runtime-env.ts b/packages/ui/src/lib/runtime-env.ts
index 200d87af..3f90374d 100644
--- a/packages/ui/src/lib/runtime-env.ts
+++ b/packages/ui/src/lib/runtime-env.ts
@@ -17,7 +17,7 @@ declare global {
 
   interface Window {
     __CODENOMAD_WINDOW_CONTEXT__?: WindowContextKind
-    electronAPI?: unknown
+    electronAPI?: ElectronAPI
     __TAURI__?: {
       core?: TauriCoreModule
     }
diff --git a/packages/ui/src/lib/server-events.ts b/packages/ui/src/lib/server-events.ts
index 4145367d..bb747f1a 100644
--- a/packages/ui/src/lib/server-events.ts
+++ b/packages/ui/src/lib/server-events.ts
@@ -2,7 +2,11 @@ import { batch as solidBatch } from "solid-js"
 import type { WorkspaceEventPayload, WorkspaceEventType } from "../../../server/src/api-types"
 import { serverApi } from "./api-client"
 import { getClientIdentity } from "./client-identity"
-import { connectWorkspaceEvents, type WorkspaceEventConnection } from "./event-transport"
+import {
+  connectWorkspaceEvents,
+  type WorkspaceEventConnection,
+  type WorkspaceEventTransportStatus,
+} from "./event-transport"
 import { getLogger } from "./logger"
 import { retryWithBackoff, isRetryableError } from "./retry-utils"
 
@@ -21,6 +25,7 @@ function logSse(message: string, context?: Record<string, unknown>) {
 class ServerEvents {
   private handlers = new Map<WorkspaceEventType | "*", Set<(event: WorkspaceEventPayload) => void>>()
   private openHandlers = new Set<() => void>()
+  private statusHandlers = new Set<(status: WorkspaceEventTransportStatus) => void>()
   private connection: WorkspaceEventConnection | null = null
   private connectGeneration = 0
   private retryDelay = RETRY_BASE_DELAY
@@ -50,6 +55,12 @@ class ServerEvents {
           }
           this.scheduleReconnect()
         },
+        onStatus: (status) => {
+          if (generation !== this.connectGeneration) {
+            return
+          }
+          this.emitTransportStatus(status)
+        },
         onOpen: () => {
           if (generation !== this.connectGeneration) {
             return
@@ -105,6 +116,8 @@ class ServerEvents {
       this.connection = null
     }
 
+    this.emitTransportStatus("disconnected")
+
     logSse("Events stream disconnected, scheduling reconnect", { delayMs: this.retryDelay })
     this.retryTimer = setTimeout(() => {
       this.retryTimer = null
@@ -140,6 +153,10 @@ class ServerEvents {
     })
   }
 
+  private emitTransportStatus(status: WorkspaceEventTransportStatus) {
+    this.statusHandlers.forEach((handler) => handler(status))
+  }
+
   on(type: WorkspaceEventType | "*", handler: (event: WorkspaceEventPayload) => void): () => void {
     if (!this.handlers.has(type)) {
       this.handlers.set(type, new Set())
@@ -154,6 +171,11 @@ class ServerEvents {
     return () => this.openHandlers.delete(handler)
   }
 
+  onTransportStatus(handler: (status: WorkspaceEventTransportStatus) => void): () => void {
+    this.statusHandlers.add(handler)
+    return () => this.statusHandlers.delete(handler)
+  }
+
   restart(reason = "manual restart"): void {
     this.retryDelay = RETRY_BASE_DELAY
     this.clearReconnectTimer()
diff --git a/packages/ui/src/lib/settings/behavior-registry.ts b/packages/ui/src/lib/settings/behavior-registry.ts
index b28229a1..0cca660f 100644
--- a/packages/ui/src/lib/settings/behavior-registry.ts
+++ b/packages/ui/src/lib/settings/behavior-registry.ts
@@ -3,6 +3,7 @@ import type {
   Preferences,
   ExpansionPreference,
   ToolInputsVisibilityPreference,
+  VisibilityPreference,
 } from "../../stores/preferences"
 import type { Command } from "../commands"
 import { tGlobal } from "../i18n"
@@ -47,8 +48,8 @@ export type BehaviorRegistryActions = {
   togglePromptSubmitOnEnter: () => void
   toggleShowPromptVoiceInput: () => void
   setDiffViewMode: (mode: "split" | "unified") => void
-  setToolOutputExpansion: (mode: ExpansionPreference) => void
-  setDiagnosticsExpansion: (mode: ExpansionPreference) => void
+  setToolOutputExpansion: (mode: VisibilityPreference) => void
+  setDiagnosticsExpansion: (mode: VisibilityPreference) => void
   setThinkingBlocksExpansion: (mode: ExpansionPreference) => void
   setToolInputsVisibility: (mode: ToolInputsVisibilityPreference) => void
 }
@@ -65,6 +66,14 @@ function setBooleanByToggle(getCurrent: () => boolean, toggle: () => void, next:
   toggle()
 }
 
+function getToolOutputVisibility(preferences: Preferences): VisibilityPreference {
+  const defaults = preferences.toolCallExpansionDefaults
+  if (defaults.tools.other) return defaults.tools.other
+  if (defaults.preset === "minimal" || defaults.preset === "balanced") return "collapsed"
+  if (defaults.preset === "detailed" || defaults.preset === "everything") return "expanded"
+  return preferences.toolOutputExpansion ?? "expanded"
+}
+
 export function getBehaviorSettings(actions: BehaviorRegistryActions): BehaviorSetting[] {
   const prefs = actions.preferences
   const updatePreferences = actions.updatePreferences
@@ -184,15 +193,25 @@ export function getBehaviorSettings(actions: BehaviorRegistryActions): BehaviorS
       id: "behavior.toolOutputsDefault",
       titleKey: "settings.behavior.toolOutputsDefault.title",
       subtitleKey: "settings.behavior.toolOutputsDefault.subtitle",
-      get: (p) => (p.toolOutputExpansion ?? "expanded") as ExpansionPreference,
+      get: getToolOutputVisibility,
       set: (next) => {
         if (updatePreferences) {
-          updatePreferences({ toolOutputExpansion: next as ExpansionPreference })
+          const mode = next as VisibilityPreference
+          const current = prefs()
+          updatePreferences({
+            toolOutputExpansion: mode === "hidden" ? current.toolOutputExpansion : mode,
+            toolCallExpansionDefaults: {
+              ...current.toolCallExpansionDefaults,
+              preset: "custom",
+              tools: { ...current.toolCallExpansionDefaults.tools, other: mode },
+            },
+          })
           return
         }
-        actions.setToolOutputExpansion(next as ExpansionPreference)
+        actions.setToolOutputExpansion(next as VisibilityPreference)
       },
       options: [
+        { value: "hidden", labelKey: "commands.common.hidden" },
         { value: "expanded", labelKey: "commands.common.expanded" },
         { value: "collapsed", labelKey: "commands.common.collapsed" },
       ],
@@ -202,15 +221,16 @@ export function getBehaviorSettings(actions: BehaviorRegistryActions): BehaviorS
       id: "behavior.diagnosticsDefault",
       titleKey: "settings.behavior.diagnosticsDefault.title",
       subtitleKey: "settings.behavior.diagnosticsDefault.subtitle",
-      get: (p) => (p.diagnosticsExpansion ?? "expanded") as ExpansionPreference,
+      get: (p) => (p.diagnosticsExpansion ?? "expanded") as VisibilityPreference,
       set: (next) => {
         if (updatePreferences) {
-          updatePreferences({ diagnosticsExpansion: next as ExpansionPreference })
+          updatePreferences({ diagnosticsExpansion: next as VisibilityPreference })
           return
         }
-        actions.setDiagnosticsExpansion(next as ExpansionPreference)
+        actions.setDiagnosticsExpansion(next as VisibilityPreference)
       },
       options: [
+        { value: "hidden", labelKey: "commands.common.hidden" },
         { value: "expanded", labelKey: "commands.common.expanded" },
         { value: "collapsed", labelKey: "commands.common.collapsed" },
       ],
@@ -434,16 +454,20 @@ export function getBehaviorCommands(actions: BehaviorRegistryActions): Command[]
     {
       id: "tool-output-default-visibility",
       label: () => {
-        const mode = actions.preferences().toolOutputExpansion || "expanded"
-        const state = mode === "expanded" ? tGlobal("commands.common.expanded") : tGlobal("commands.common.collapsed")
+        const mode = getToolOutputVisibility(actions.preferences())
+        const state = mode === "expanded"
+          ? tGlobal("commands.common.expanded")
+          : mode === "collapsed"
+            ? tGlobal("commands.common.collapsed")
+            : tGlobal("commands.common.hidden")
         return tGlobal("commands.toolOutputsDefault.label", { state })
       },
       description: () => tGlobal("commands.toolOutputsDefault.description"),
       category: "System",
       keywords: () => splitKeywords("commands.toolOutputsDefault.keywords"),
       action: () => {
-        const mode = actions.preferences().toolOutputExpansion || "expanded"
-        const next: ExpansionPreference = mode === "expanded" ? "collapsed" : "expanded"
+        const mode = getToolOutputVisibility(actions.preferences())
+        const next: VisibilityPreference = mode === "hidden" ? "collapsed" : mode === "collapsed" ? "expanded" : "hidden"
         actions.setToolOutputExpansion(next)
       },
     },
@@ -451,7 +475,11 @@ export function getBehaviorCommands(actions: BehaviorRegistryActions): Command[]
       id: "diagnostics-default-visibility",
       label: () => {
         const mode = actions.preferences().diagnosticsExpansion || "expanded"
-        const state = mode === "expanded" ? tGlobal("commands.common.expanded") : tGlobal("commands.common.collapsed")
+        const state = mode === "expanded"
+          ? tGlobal("commands.common.expanded")
+          : mode === "collapsed"
+            ? tGlobal("commands.common.collapsed")
+            : tGlobal("commands.common.hidden")
         return tGlobal("commands.diagnosticsDefault.label", { state })
       },
       description: () => tGlobal("commands.diagnosticsDefault.description"),
@@ -459,7 +487,7 @@ export function getBehaviorCommands(actions: BehaviorRegistryActions): Command[]
       keywords: () => splitKeywords("commands.diagnosticsDefault.keywords"),
       action: () => {
         const mode = actions.preferences().diagnosticsExpansion || "expanded"
-        const next: ExpansionPreference = mode === "expanded" ? "collapsed" : "expanded"
+        const next: VisibilityPreference = mode === "hidden" ? "collapsed" : mode === "collapsed" ? "expanded" : "hidden"
         actions.setDiagnosticsExpansion(next)
       },
     },
diff --git a/packages/ui/src/lib/speech-capabilities.test.ts b/packages/ui/src/lib/speech-capabilities.test.ts
new file mode 100644
index 00000000..f7d72a45
--- /dev/null
+++ b/packages/ui/src/lib/speech-capabilities.test.ts
@@ -0,0 +1,75 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+type Caps = Record<string, unknown>
+
+function normalizeCapabilities(result: Caps): Caps {
+  if (result.sttConfigured === undefined) result.sttConfigured = result.configured
+  if (result.ttsConfigured === undefined) result.ttsConfigured = result.configured
+  if (result.separateProviders === undefined) result.separateProviders = false
+  return result
+}
+
+describe("normalizeCapabilities (old server compat)", () => {
+  it("derives sttConfigured/ttsConfigured from configured when absent", () => {
+    const legacy: Caps = {
+      available: true,
+      configured: true,
+      provider: "openai-compatible",
+      supportsStt: true,
+      supportsTts: true,
+      supportsStreamingTts: true,
+      sttModel: "whisper-1",
+      ttsModel: "tts-1",
+      ttsVoice: "alloy",
+      ttsFormats: ["mp3"],
+      streamingTtsFormats: ["mp3"],
+    }
+    const normalized = normalizeCapabilities(legacy)
+    assert.equal(normalized.sttConfigured, true)
+    assert.equal(normalized.ttsConfigured, true)
+    assert.equal(normalized.separateProviders, false)
+  })
+
+  it("preserves explicit directional values from new server", () => {
+    const modern: Caps = {
+      available: true,
+      configured: false,
+      provider: "openai-compatible",
+      supportsStt: true,
+      supportsTts: true,
+      supportsStreamingTts: true,
+      sttModel: "whisper-1",
+      ttsModel: "tts-1",
+      ttsVoice: "alloy",
+      ttsFormats: ["mp3"],
+      streamingTtsFormats: ["mp3"],
+      separateProviders: true,
+      sttConfigured: true,
+      ttsConfigured: false,
+    }
+    const normalized = normalizeCapabilities(modern)
+    assert.equal(normalized.sttConfigured, true, "must not overwrite explicit sttConfigured")
+    assert.equal(normalized.ttsConfigured, false, "must not overwrite explicit ttsConfigured")
+    assert.equal(normalized.separateProviders, true)
+  })
+
+  it("derives false when legacy configured is false", () => {
+    const legacy: Caps = {
+      available: true,
+      configured: false,
+      provider: "openai-compatible",
+      supportsStt: true,
+      supportsTts: true,
+      supportsStreamingTts: true,
+      sttModel: "whisper-1",
+      ttsModel: "tts-1",
+      ttsVoice: "alloy",
+      ttsFormats: ["mp3"],
+      streamingTtsFormats: ["mp3"],
+    }
+    const normalized = normalizeCapabilities(legacy)
+    assert.equal(normalized.sttConfigured, false)
+    assert.equal(normalized.ttsConfigured, false)
+  })
+})
diff --git a/packages/ui/src/lib/speech-card.test.ts b/packages/ui/src/lib/speech-card.test.ts
new file mode 100644
index 00000000..6aa7754b
--- /dev/null
+++ b/packages/ui/src/lib/speech-card.test.ts
@@ -0,0 +1,85 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { buildDirSave } from "./speech-dir-save"
+import { buildSpeechPatch } from "./speech-patch"
+
+describe("card-level regression: separate → shared preserves directional config", () => {
+  it("shared-mode save patch does NOT include stt/tts cleanup", () => {
+    const patch = buildSpeechPatch({
+      separateProviders: false,
+      baseUrl: "https://api.openai.com/v1",
+      sttModel: "whisper-1",
+      ttsModel: "tts-1",
+      ttsVoice: "alloy",
+      playbackMode: "streaming",
+      ttsFormat: "mp3",
+    })
+    assert.equal("stt" in patch, false, "shared-mode patch must not touch stt")
+    assert.equal("tts" in patch, false, "shared-mode patch must not touch tts")
+    assert.equal(patch.separateProviders, false)
+  })
+})
+
+describe("buildDirSave", () => {
+  it("does NOT include baseUrl when it matches stored value (no key deletion)", () => {
+    const stored = "https://api.groq.com/v1"
+    const result = buildDirSave(false, "", stored, "whisper-large-v3", stored, "whisper-1")
+    assert.equal("baseUrl" in result, false, "baseUrl must not be in patch when unchanged — prevents server from clearing key")
+    assert.equal("apiKey" in result, false, "apiKey must not be in patch when no new key entered")
+  })
+
+  it("clears stored key when URL differs from stored (old-server safe)", () => {
+    const result = buildDirSave(false, "", "https://api.new.com/v1", "whisper-large-v3", "https://api.old.com/v1", "whisper-1")
+    assert.equal(result.baseUrl, "https://api.new.com/v1")
+    assert.equal(result.apiKey, null, "apiKey must be null when URL changes without new key — old-server safe")
+  })
+
+  it("includes apiKey when user enters a new key", () => {
+    const result = buildDirSave(false, "sk-new-key", "https://api.groq.com/v1", "whisper-large-v3", "https://api.groq.com/v1", "whisper-1")
+    assert.equal(result.apiKey, "sk-new-key")
+    assert.equal("baseUrl" in result, false, "baseUrl unchanged should not be in patch")
+  })
+
+  it("clears all fields when clearKey is true", () => {
+    const result = buildDirSave(true, "", "", "", undefined, "whisper-1")
+    assert.deepEqual(result, { apiKey: null, baseUrl: null, model: null })
+  })
+
+  it("sends null model when it matches shared model", () => {
+    const result = buildDirSave(false, "sk-key", "https://api.groq.com/v1", "whisper-1", "https://api.groq.com/v1", "whisper-1")
+    assert.equal(result.model, null, "matching shared model should not be persisted as directional override")
+  })
+
+  it("does not clear stored key when saving unrelated fields (model only)", () => {
+    const stored = "https://api.groq.com/v1"
+    const result = buildDirSave(false, "", stored, "whisper-large-v3", stored, "whisper-1")
+    assert.equal("apiKey" in result, false, "must not include apiKey when only model changed")
+    assert.equal("baseUrl" in result, false, "must not include baseUrl when unchanged")
+    assert.equal(result.model, "whisper-large-v3")
+  })
+})
+
+describe("card-level regression: shared key survives shared → separate", () => {
+  it("separate-mode patch includes shared apiKey when provided", () => {
+    const patch = buildSpeechPatch({
+      separateProviders: true,
+      apiKey: "sk-shared-key",
+      ttsVoice: "alloy",
+      playbackMode: "streaming",
+      ttsFormat: "mp3",
+    })
+    assert.equal(patch.apiKey, "sk-shared-key")
+    assert.equal(patch.separateProviders, true)
+  })
+
+  it("separate-mode patch includes shared apiKey null when clearing", () => {
+    const patch = buildSpeechPatch({
+      separateProviders: true,
+      apiKey: null,
+      ttsVoice: "alloy",
+      playbackMode: "streaming",
+      ttsFormat: "mp3",
+    })
+    assert.equal(patch.apiKey, null)
+  })
+})
diff --git a/packages/ui/src/lib/speech-dir-save.ts b/packages/ui/src/lib/speech-dir-save.ts
new file mode 100644
index 00000000..d6c15f94
--- /dev/null
+++ b/packages/ui/src/lib/speech-dir-save.ts
@@ -0,0 +1,24 @@
+export function buildDirSave(
+  clearKey: boolean,
+  draftApiKey: string,
+  draftBaseUrl: string,
+  draftModel: string,
+  storedBaseUrl: string | undefined,
+  sharedModel: string,
+): { apiKey?: string | null; baseUrl?: string | null; model?: string | null } {
+  if (clearKey) return { apiKey: null, baseUrl: null, model: null }
+  const newKey = draftApiKey.trim()
+  const baseUrlChanged = (draftBaseUrl.trim() || "") !== (storedBaseUrl || "")
+  const modelMatchesShared = draftModel.trim() === sharedModel.trim()
+  if (baseUrlChanged) {
+    return {
+      ...(newKey ? { apiKey: newKey } : { apiKey: null }),
+      baseUrl: draftBaseUrl.trim() || null,
+      model: modelMatchesShared ? null : (draftModel.trim() || null),
+    }
+  }
+  return {
+    ...(newKey ? { apiKey: newKey } : {}),
+    model: modelMatchesShared ? null : (draftModel.trim() || null),
+  }
+}
diff --git a/packages/ui/src/lib/speech-patch.ts b/packages/ui/src/lib/speech-patch.ts
new file mode 100644
index 00000000..0c7f9940
--- /dev/null
+++ b/packages/ui/src/lib/speech-patch.ts
@@ -0,0 +1,27 @@
+import type { SpeechSettingsUpdate } from "../stores/preferences"
+
+export function buildSpeechPatch(updates: SpeechSettingsUpdate): Record<string, unknown> {
+  const patch: Record<string, unknown> = {}
+
+  if (updates.separateProviders !== undefined) patch.separateProviders = updates.separateProviders
+  if (updates.apiKey !== undefined) patch.apiKey = updates.apiKey
+  if (updates.baseUrl !== undefined) patch.baseUrl = updates.baseUrl?.trim() || null
+  if (updates.sttModel !== undefined) patch.sttModel = updates.sttModel?.trim() || null
+  if (updates.ttsModel !== undefined) patch.ttsModel = updates.ttsModel?.trim() || null
+  if (updates.ttsVoice !== undefined) patch.ttsVoice = updates.ttsVoice?.trim() || null
+  if (updates.playbackMode !== undefined) patch.playbackMode = updates.playbackMode
+  if (updates.ttsFormat !== undefined) patch.ttsFormat = updates.ttsFormat
+
+  for (const dir of ["stt", "tts"] as const) {
+    const dirUpdate = updates[dir]
+    if (dirUpdate) {
+      const dirPatch: Record<string, unknown> = {}
+      if (dirUpdate.apiKey !== undefined) dirPatch.apiKey = dirUpdate.apiKey
+      if (dirUpdate.baseUrl !== undefined) dirPatch.baseUrl = dirUpdate.baseUrl?.trim() || null
+      if (dirUpdate.model !== undefined) dirPatch.model = dirUpdate.model?.trim() || null
+      if (Object.keys(dirPatch).length > 0) patch[dir] = dirPatch
+    }
+  }
+
+  return patch
+}
diff --git a/packages/ui/src/lib/sse-manager.ts b/packages/ui/src/lib/sse-manager.ts
index 809cf039..eb788067 100644
--- a/packages/ui/src/lib/sse-manager.ts
+++ b/packages/ui/src/lib/sse-manager.ts
@@ -24,13 +24,18 @@ import type {
 } from "@opencode-ai/sdk/v2"
 import type { LegacyPermissionAskedEvent, LegacyPermissionRepliedEvent } from "../types/permission"
 import { serverEvents } from "./server-events"
+import type { WorkspaceEventTransportStatus } from "./event-transport"
 import type {
   BackgroundProcess,
   InstanceStreamEvent,
-  InstanceStreamStatus,
   WorkspaceEventPayload,
 } from "../../../server/src/api-types"
 import { getLogger } from "./logger"
+import {
+  deriveDisplayConnectionStatus,
+  seedConnectionStatusIfMissing,
+  type ConnectionStatus,
+} from "./connection-status"
 
 const log = getLogger("sse")
 
@@ -68,7 +73,24 @@ interface ServerInstanceDisposedEvent {
   }
 }
 
+export interface WorktreeReadyEvent {
+  type: "worktree.ready"
+  directory?: string
+  properties: {
+    name: string
+    branch?: string
+  }
+}
+
 type EventSessionCreated = Omit<EventSessionUpdated, "type"> & { type: "session.created" }
+export interface EventSessionDeleted {
+  type: "session.deleted"
+  properties?: {
+    info?: { id?: string }
+    id?: string
+    sessionID?: string
+  }
+}
 
 type SSEEvent =
   | MessageUpdateEvent
@@ -78,6 +100,7 @@ type SSEEvent =
   | MessagePartDeltaEvent
   | EventSessionCreated
   | EventSessionUpdated
+  | EventSessionDeleted
   | EventSessionCompacted
   | EventSessionError
   | EventSessionIdle
@@ -96,14 +119,16 @@ type SSEEvent =
   | BackgroundProcessUpdatedEvent
   | BackgroundProcessRemovedEvent
   | ServerInstanceDisposedEvent
+  | WorktreeReadyEvent
   | { type: string; properties?: Record<string, unknown> }
 
-type ConnectionStatus = InstanceStreamStatus
-
 const [connectionStatus, setConnectionStatus] = createSignal<Map<string, ConnectionStatus>>(new Map())
+const [transportStatus, setTransportStatus] = createSignal<WorkspaceEventTransportStatus>("connecting")
 
 class SSEManager {
   constructor() {
+    log.info("sseManager initialized: listening for SSE disconnect and reconnect")
+
     serverEvents.on("instance.eventStatus", (event) => {
       const payload = event as InstanceStatusPayload
       this.updateConnectionStatus(payload.instanceId, payload.status)
@@ -121,12 +146,21 @@ class SSEManager {
       this.updateConnectionStatus(payload.instanceId, "connected")
       this.handleEvent(payload.instanceId, payload.event as SSEEvent)
     })
+
+    serverEvents.onTransportStatus((status) => {
+      log.info("SSE transport status changed", { status })
+      setTransportStatus(status)
+    })
   }
 
   seedStatus(instanceId: string, status: ConnectionStatus) {
     this.updateConnectionStatus(instanceId, status)
   }
 
+  seedStatusIfMissing(instanceId: string, status: ConnectionStatus) {
+    setConnectionStatus((prev) => seedConnectionStatusIfMissing(prev, instanceId, status))
+  }
+
   private handleEvent(instanceId: string, event: SSEEvent | InstanceStreamEvent): void {
     if (!event || typeof event !== "object" || typeof (event as { type?: unknown }).type !== "string") {
       log.warn("Dropping malformed event", event)
@@ -157,6 +191,9 @@ class SSEManager {
       case "session.created":
         this.onSessionUpdate?.(instanceId, event as EventSessionUpdated)
         break
+      case "session.deleted":
+        this.onSessionDeleted?.(instanceId, event as EventSessionDeleted)
+        break
       case "session.compacted":
         this.onSessionCompacted?.(instanceId, event as EventSessionCompacted)
         break
@@ -211,6 +248,16 @@ class SSEManager {
       case "server.instance.disposed":
         this.onInstanceDisposed?.(instanceId, event as ServerInstanceDisposedEvent)
         break
+      case "worktree.ready":
+        try {
+          const result = this.onWorktreeReady?.(instanceId, event as WorktreeReadyEvent)
+          void result?.catch((error) => {
+            log.warn("Failed to handle worktree ready event", { instanceId, error })
+          })
+        } catch (error) {
+          log.warn("Failed to handle worktree ready event", { instanceId, error })
+        }
+        break
       default:
         log.warn("Unknown SSE event type", { type: event.type })
     }
@@ -230,6 +277,7 @@ class SSEManager {
   onMessagePartDelta?: (instanceId: string, event: MessagePartDeltaEvent) => void
   onMessagePartRemoved?: (instanceId: string, event: MessagePartRemovedEvent) => void
   onSessionUpdate?: (instanceId: string, event: EventSessionUpdated) => void
+  onSessionDeleted?: (instanceId: string, event: EventSessionDeleted) => void
   onSessionCompacted?: (instanceId: string, event: EventSessionCompacted) => void
   onSessionError?: (instanceId: string, event: EventSessionError) => void
   onTuiToast?: (instanceId: string, event: TuiToastEvent) => void
@@ -243,10 +291,11 @@ class SSEManager {
   onBackgroundProcessUpdated?: (instanceId: string, event: BackgroundProcessUpdatedEvent) => void
   onBackgroundProcessRemoved?: (instanceId: string, event: BackgroundProcessRemovedEvent) => void
   onInstanceDisposed?: (instanceId: string, event: ServerInstanceDisposedEvent) => void
+  onWorktreeReady?: (instanceId: string, event: WorktreeReadyEvent) => void | Promise<void>
   onConnectionLost?: (instanceId: string, reason: string) => void | Promise<void>
 
   getStatus(instanceId: string): ConnectionStatus | null {
-    return connectionStatus().get(instanceId) ?? null
+    return deriveDisplayConnectionStatus(connectionStatus().get(instanceId) ?? null, transportStatus())
   }
 
   getStatuses() {
diff --git a/packages/ui/src/lib/trailing-resync.test.ts b/packages/ui/src/lib/trailing-resync.test.ts
new file mode 100644
index 00000000..7e4a5d16
--- /dev/null
+++ b/packages/ui/src/lib/trailing-resync.test.ts
@@ -0,0 +1,54 @@
+import assert from "node:assert/strict"
+import { it } from "node:test"
+import { TrailingResyncCoordinator, waitForSettledPrerequisite } from "./trailing-resync.ts"
+function deferred() {
+  let resolve!: () => void, reject!: (error: unknown) => void
+  const promise = new Promise<void>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise; reject = rejectPromise
+  })
+  return { promise, resolve, reject }
+}
+const turn = () => new Promise<void>((resolve) => setImmediate(resolve))
+const coordinatorFor = (passes: ReturnType<typeof deferred>[], errors: unknown[] = []) => {
+  let calls = 0
+  return {
+    coordinator: new TrailingResyncCoordinator(async () => passes[calls++]!.promise, (_key, error) => errors.push(error)),
+    calls: () => calls,
+  }
+}
+it("runs a trailing resync when reconnect occurs during an active pass", async () => {
+  const passes = [deferred(), deferred()]
+  const { coordinator, calls } = coordinatorFor(passes)
+  const settled = coordinator.request("workspace-1")
+  coordinator.request("workspace-1"); await Promise.resolve()
+  assert.equal(calls(), 1)
+  passes[0]!.resolve(); await turn()
+  assert.equal(calls(), 2)
+  passes[1]!.resolve(); await settled
+})
+it("retries a queued resync after the active pass fails", async () => {
+  const passes = [deferred(), deferred()]
+  const errors: unknown[] = []
+  const { coordinator, calls } = coordinatorFor(passes, errors)
+  const settled = coordinator.request("workspace-1")
+  coordinator.request("workspace-1"); await Promise.resolve()
+  passes[0]!.reject(new Error("transport reset")); await turn()
+  assert.equal(calls(), 2)
+  passes[1]!.resolve(); await settled
+  assert.equal(errors.length, 1)
+})
+it("does not lose a request queued as the previous pass settles", async () => {
+  const firstPass = deferred()
+  let calls = 0
+  const coordinator = new TrailingResyncCoordinator(async () => {
+    calls += 1
+    if (calls === 1) await firstPass.promise
+  }, () => undefined)
+  const first = coordinator.request("workspace-1")
+  const boundaryRequest = firstPass.promise.then(() => coordinator.request("workspace-1"))
+  firstPass.resolve(); await first; await boundaryRequest
+  assert.equal(calls, 2)
+})
+it("continues recovery after a prerequisite rejects", async () => {
+  await assert.doesNotReject(waitForSettledPrerequisite(Promise.reject(new Error("initial hydration failed"))))
+})
diff --git a/packages/ui/src/lib/trailing-resync.ts b/packages/ui/src/lib/trailing-resync.ts
new file mode 100644
index 00000000..3a52e80f
--- /dev/null
+++ b/packages/ui/src/lib/trailing-resync.ts
@@ -0,0 +1,32 @@
+export class TrailingResyncCoordinator {
+  private readonly tails = new Map<string, Promise<void>>()
+
+  constructor(
+    private readonly run: (key: string) => Promise<void>,
+    private readonly onError: (key: string, error: unknown) => void,
+  ) {}
+
+  request(key: string): Promise<void> {
+    const previous = this.tails.get(key) ?? Promise.resolve()
+    const task = previous.then(async () => {
+      try {
+        await this.run(key)
+      } catch (error) {
+        this.onError(key, error)
+      }
+    })
+    const tracked = task.finally(() => {
+      if (this.tails.get(key) === tracked) this.tails.delete(key)
+    })
+    this.tails.set(key, tracked)
+    return tracked
+  }
+}
+
+export async function waitForSettledPrerequisite(prerequisite: Promise<void> | undefined): Promise<void> {
+  try {
+    await prerequisite
+  } catch {
+    // A resync is the recovery path for a failed prerequisite.
+  }
+}
diff --git a/packages/ui/src/main.tsx b/packages/ui/src/main.tsx
index 4be1fc57..dcc61281 100644
--- a/packages/ui/src/main.tsx
+++ b/packages/ui/src/main.tsx
@@ -6,6 +6,7 @@ import { InstanceConfigProvider } from "./stores/instance-config"
 import { runtimeEnv } from "./lib/runtime-env"
 import { I18nProvider, preloadLocaleMessages } from "./lib/i18n"
 import { storage } from "./lib/storage"
+import { initializeClientState } from "./stores/client-state"
 import "./index.css"
 import "@git-diff-view/solid/styles/diff-view-pure.css"
 
@@ -23,6 +24,8 @@ if (typeof document !== "undefined") {
 }
 
 async function bootstrap() {
+  await initializeClientState()
+
   if (typeof document !== "undefined") {
     // renderer/index.html currently seeds a dark theme to avoid a white flash.
     // Reset to CSS defaults immediately so the first render matches system
diff --git a/packages/ui/src/stores/abort-created-workspace-cleanup.test.ts b/packages/ui/src/stores/abort-created-workspace-cleanup.test.ts
new file mode 100644
index 00000000..b6f7a4d9
--- /dev/null
+++ b/packages/ui/src/stores/abort-created-workspace-cleanup.test.ts
@@ -0,0 +1,250 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { AbortCreatedWorkspaceCleanup } from "./abort-created-workspace-cleanup.ts"
+
+interface TestWorkspace { id: string; status: "starting" | "ready"; requestId?: string; reused?: boolean }
+const workspace = (id: string, requestId?: string): TestWorkspace => ({ id, status: "ready", requestId })
+async function flushPromises() { await Promise.resolve(); await Promise.resolve() }
+function createHarness(options: { failures?: number; pending?: boolean; retryDelay?: number } = {}) {
+  let discardCalls = 0
+  let finishDiscard: (() => void) | undefined
+  const discarded: TestWorkspace[] = []
+  const waits: Array<{ delayMs: number; resolve: () => void }> = []
+  const restored: TestWorkspace[] = []
+  const cleanup = new AbortCreatedWorkspaceCleanup<TestWorkspace>({
+    discardWorkspace: async (item) => {
+      discardCalls += 1
+      discarded.push(item)
+      if (options.pending) await new Promise<void>((resolve) => { finishDiscard = resolve })
+      if (discardCalls <= (options.failures ?? 0)) throw new Error("server unavailable")
+    },
+    restoreWorkspace: (value) => restored.push(value),
+    retryDelaysMs: options.retryDelay === undefined ? [] : [options.retryDelay],
+    wait: (delayMs) => new Promise<void>((resolve) => waits.push({ delayMs, resolve })),
+  })
+  return {
+    cleanup, discarded, restored, waits,
+    get discardCalls() { return discardCalls },
+    finishDiscard: () => finishDiscard?.(),
+  }
+}
+
+describe("abort-created workspace cleanup", () => {
+  it("late creation cancellation cannot leak a restore-created workspace", async () => {
+    const item = workspace("late creation", "restore-request")
+    const harness = createHarness()
+    harness.cleanup.beginRequest(item.requestId!)
+    assert.equal(harness.cleanup.trackPendingRequest(item), true)
+    await harness.cleanup.discardTracked(item.id, { retainTombstone: true })
+    harness.cleanup.finishRequest(item.requestId!)
+    assert.equal(harness.discardCalls, 1)
+    assert.equal(harness.discarded[0]?.requestId, "restore-request")
+    assert.deepEqual(harness.restored, [])
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true)
+  })
+
+  it("does not tombstone a reused workspace after request cancellation", async () => {
+    const item = { ...workspace("shared workspace", "restore-request"), reused: true }, harness = createHarness()
+    harness.cleanup.beginRequest(item.requestId!)
+    harness.cleanup.quarantineRequest(item.requestId!)
+    assert.equal(harness.cleanup.trackPendingRequest(item), true)
+    await flushPromises()
+    assert.equal(harness.discardCalls, 1)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), false)
+  })
+
+  it("forgets only the matching request for a shared workspace", () => {
+    const leader = workspace("shared", "leader"), harness = createHarness()
+    harness.cleanup.track(leader)
+    harness.cleanup.forgetRequest(leader.id, "follower")
+    assert.equal(harness.cleanup.get(leader.id)?.requestId, "leader")
+    harness.cleanup.forgetRequest(leader.id, "leader")
+    assert.equal(harness.cleanup.get(leader.id), undefined)
+  })
+
+  it("keeps a workspace user-owned when release succeeds during cancellation", async () => {
+    const item = workspace("released-during-cancel", "restore-request"), harness = createHarness()
+    harness.cleanup.track(item)
+    let finishRelease!: () => void
+    const release = harness.cleanup.releaseAfter(item.id, () => new Promise<void>((resolve) => { finishRelease = resolve }))
+    await harness.cleanup.discardTracked(item.id, { retainTombstone: true })
+    finishRelease()
+    const released = await release
+    harness.cleanup.track(item)
+    await harness.cleanup.discardTracked(item.id, { retainTombstone: true })
+    assert.equal(released?.id, item.id)
+    assert.equal(harness.cleanup.owns(item.id), false)
+    assert.equal(harness.discardCalls, 0)
+  })
+
+  it("restores cleanup ownership when server release fails", async () => {
+    const item = workspace("failed-release", "restore-request"), harness = createHarness()
+    harness.cleanup.track(item)
+    await assert.rejects(harness.cleanup.releaseAfter(item.id, () => Promise.reject(new Error("release failed"))))
+    assert.equal(harness.cleanup.owns(item.id), true)
+    await harness.cleanup.discardTracked(item.id)
+    assert.equal(harness.discardCalls, 1)
+  })
+
+  it("retries rejected cancellation and releases quarantine after success", async () => {
+    const item = workspace("created"), harness = createHarness({ failures: 1, retryDelay: 25 })
+    harness.cleanup.track(item)
+    const completion = harness.cleanup.discardTracked(item.id)
+    await flushPromises()
+    assert.equal(harness.discardCalls, 1)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true)
+    assert.deepEqual(harness.waits.map(({ delayMs }) => delayMs), [25])
+    harness.waits[0]?.resolve(); await completion
+    assert.equal(harness.discardCalls, 2)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), false)
+    assert.equal(harness.cleanup.owns(item.id), false)
+    assert.deepEqual(harness.restored, [])
+  })
+
+  it("ignores matching events only while cancellation is pending", async () => {
+    const item = workspace("created"), harness = createHarness({ pending: true })
+    const completion = harness.cleanup.discardCreated(item)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true)
+    assert.equal(harness.cleanup.shouldIgnoreEvent("pre-existing"), false)
+    harness.finishDiscard(); await completion
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), false)
+  })
+
+  it("retains cancellation quarantine across delayed events and create resolution", async () => {
+    const item = workspace("cancelled-restore"), harness = createHarness()
+    harness.cleanup.track(item)
+    await harness.cleanup.discardTracked(item.id, { retainTombstone: true })
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true, "delayed created/started events stay quarantined")
+    harness.cleanup.track(item)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true, "late create resolution stays quarantined")
+    assert.equal(harness.cleanup.owns(item.id), true)
+  })
+
+  it("keeps failed cancellation correlation quarantined until late creation is reconciled", async () => {
+    const item = workspace("late-after-failed-cancel", "failed-request"), harness = createHarness({ pending: true })
+    harness.cleanup.beginRequest("failed-request"); harness.cleanup.quarantineRequest("failed-request")
+    assert.equal(harness.cleanup.trackPendingRequest(item), true)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true, "late workspace.created is never admitted")
+    harness.finishDiscard(); await flushPromises()
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true, "reconciled creation retains its tombstone")
+  })
+
+  it("adopts an event-before-abort workspace into one bounded cleanup", async () => {
+    const item = workspace("event-before-abort", "restore-request")
+    const harness = createHarness({ failures: 1, retryDelay: 25 })
+    harness.cleanup.beginRequest(item.requestId!)
+    assert.equal(harness.cleanup.trackPendingRequest(item), true)
+
+    const cleanup = harness.cleanup.quarantineRequest(item.requestId!)
+    const duplicate = harness.cleanup.quarantineRequest(item.requestId!)
+    await flushPromises()
+    assert.equal(harness.discardCalls, 1, "quarantine does not start a parallel cancellation")
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true)
+    assert.deepEqual(harness.waits.map(({ delayMs }) => delayMs), [25])
+
+    harness.waits[0]?.resolve()
+    await Promise.all([cleanup, duplicate])
+    assert.equal(harness.discardCalls, 2, "the failed delete is retried once")
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true)
+  })
+
+  it("clears a durable tombstone only for explicit user-owned create correlation", async () => {
+    const item = workspace("reused-id"), harness = createHarness()
+    await harness.cleanup.discardCreated(item, { retainTombstone: true })
+    harness.cleanup.track(item); harness.cleanup.release(item.id)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true, "ordinary track/release cannot clear tombstone")
+    harness.cleanup.releaseTombstoneForUserCreate(item.id)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), false)
+    assert.equal(harness.cleanup.owns(item.id), false)
+    harness.cleanup.releaseTombstoneForUserCreate("ordinary-user-workspace")
+    assert.equal(harness.cleanup.owns("ordinary-user-workspace"), false)
+  })
+
+  it("restores a running workspace after bounded cancellation failures", async () => {
+    const item = workspace("still-running"), harness = createHarness({ failures: 2, retryDelay: 50 })
+    const completion = harness.cleanup.discardCreated(item)
+    await flushPromises()
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true)
+    harness.waits[0]?.resolve(); await completion
+    assert.equal(harness.discardCalls, 2)
+    assert.deepEqual(harness.restored, [item])
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), false)
+    assert.equal(harness.cleanup.owns(item.id), false)
+  })
+
+  it("restores the newest correlated descriptor after cancellation failures", async () => {
+    const starting = { ...workspace("progressed", "request"), status: "starting" as const }
+    const ready = { ...starting, status: "ready" as const }
+    const harness = createHarness({ failures: 2, retryDelay: 50 })
+    harness.cleanup.track(starting)
+    const completion = harness.cleanup.discardTracked(starting.id)
+    await flushPromises()
+    harness.cleanup.track(ready)
+    harness.waits[0]?.resolve(); await completion
+    assert.equal(harness.discarded[1]?.status, "ready")
+    assert.deepEqual(harness.restored, [ready])
+  })
+
+  it("never discards untracked or released workspaces", async () => {
+    const harness = createHarness()
+    await harness.cleanup.discardTracked("pre-existing")
+    harness.cleanup.track(workspace("completed-restore")); harness.cleanup.release("completed-restore")
+    harness.cleanup.track(workspace("completed-restore"))
+    await harness.cleanup.discardTracked("completed-restore")
+    assert.equal(harness.discardCalls, 0)
+  })
+
+  it("transfers a tracked workspace to user ownership before cleanup", async () => {
+    const item = workspace("selected-during-restore", "restore-request"), harness = createHarness()
+    harness.cleanup.track(item)
+    assert.equal(harness.cleanup.release(item.id), item)
+    await harness.cleanup.discardTracked(item.id, { retainTombstone: true })
+    assert.equal(harness.cleanup.owns(item.id), false)
+    assert.equal(harness.discardCalls, 0)
+  })
+
+  it("does not start a lazy release after explicit close owns cancellation", async () => {
+    const item = workspace("closed-before-release", "restore-request")
+    const harness = createHarness({ pending: true })
+    harness.cleanup.track(item)
+    const deletion = harness.cleanup.discardTracked(item.id, { retainTombstone: true })
+    let releaseCalls = 0
+
+    const released = await harness.cleanup.releaseAfter(item.id, async () => { releaseCalls += 1 })
+
+    assert.equal(released, undefined)
+    assert.equal(releaseCalls, 0)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true)
+    harness.finishDiscard()
+    await deletion
+  })
+
+  it("correlates created before resolution and quarantines explicit-close races", async () => {
+    const item = { ...workspace("slow-restore", "restore-request"), status: "starting" as const }
+    const harness = createHarness({ pending: true })
+    harness.cleanup.beginRequest("restore-request")
+    assert.equal(harness.cleanup.trackPendingRequest(item), true)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), false, "initial correlated created event is accepted")
+    const deletion = harness.cleanup.discardTracked(item.id, { retainTombstone: true })
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true, "started event and create resolution are quarantined")
+    assert.equal(harness.discardCalls, 1)
+    harness.finishDiscard(); await deletion; harness.cleanup.finishRequest("restore-request")
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true, "late created/started events stay quarantined")
+    harness.cleanup.track(item)
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true, "late create resolution stays quarantined")
+    assert.equal(harness.cleanup.owns(item.id), true)
+  })
+
+  it("releases explicit-close quarantine after failed deletion reconciliation", async () => {
+    const item = workspace("reconcile", "request"), harness = createHarness({ failures: 2, retryDelay: 10 })
+    harness.cleanup.beginRequest("request"); assert.equal(harness.cleanup.trackPendingRequest(item), true)
+    const completion = harness.cleanup.discardTracked(item.id, { retainTombstone: true })
+    await flushPromises()
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), true)
+    harness.waits[0]?.resolve(); await completion
+    assert.deepEqual(harness.restored, [item])
+    assert.equal(harness.cleanup.shouldIgnoreEvent(item.id), false)
+    assert.equal(harness.cleanup.owns(item.id), false)
+  })
+})
diff --git a/packages/ui/src/stores/abort-created-workspace-cleanup.ts b/packages/ui/src/stores/abort-created-workspace-cleanup.ts
new file mode 100644
index 00000000..0e678f4a
--- /dev/null
+++ b/packages/ui/src/stores/abort-created-workspace-cleanup.ts
@@ -0,0 +1,179 @@
+import { retryWithBackoff } from "../lib/retry-utils"
+
+interface CreatedWorkspace {
+  id: string
+  requestId?: string
+  reused?: boolean
+}
+
+interface PendingCleanup<T> {
+  workspace: T
+  completion: Promise<void>
+  resolve: () => void
+  retainTombstone: boolean
+}
+
+type OwnedWorkspace<T> = { workspace: T } | PendingCleanup<T> | { tombstone: true } | { released: true }
+
+interface AbortCreatedWorkspaceCleanupOptions<T> {
+  discardWorkspace: (workspace: T) => Promise<void>
+  restoreWorkspace: (workspace: T) => void
+  retryDelaysMs?: readonly number[]
+  wait?: (delayMs: number) => Promise<void>
+  onPermanentFailure?: (workspace: T, error: unknown) => void
+}
+
+const DEFAULT_RETRY_DELAYS_MS = [250, 1_000, 2_000] as const
+
+export class AbortCreatedWorkspaceCleanup<T extends CreatedWorkspace> {
+  private readonly owned = new Map<string, OwnedWorkspace<T>>()
+  private readonly pendingRequestIds = new Map<string, boolean>()
+
+  constructor(private readonly options: AbortCreatedWorkspaceCleanupOptions<T>) {}
+
+  track(workspace: T): void {
+    const entry = this.owned.get(workspace.id)
+    if (!entry) this.owned.set(workspace.id, { workspace })
+    else if ("workspace" in entry && !("released" in entry)) entry.workspace = workspace
+  }
+
+  beginRequest(requestId: string): void {
+    this.pendingRequestIds.set(requestId, false)
+  }
+
+  finishRequest(requestId: string): void {
+    this.pendingRequestIds.delete(requestId)
+  }
+
+  forgetRequest(workspaceId: string, requestId: string): void {
+    this.pendingRequestIds.delete(requestId)
+    const entry = this.owned.get(workspaceId)
+    if (entry && "workspace" in entry && !("completion" in entry) && entry.workspace.requestId === requestId) {
+      this.owned.delete(workspaceId)
+    }
+  }
+
+  quarantineRequest(requestId: string): Promise<void> | undefined {
+    if (!this.pendingRequestIds.has(requestId)) return undefined
+    this.pendingRequestIds.set(requestId, true)
+    for (const [workspaceId, entry] of this.owned) {
+      if (!("workspace" in entry) || entry.workspace.requestId !== requestId) continue
+      const cleanup = this.discardTracked(workspaceId, { retainTombstone: entry.workspace.reused !== true })
+      void cleanup.finally(() => this.finishRequest(requestId))
+      return cleanup
+    }
+    return undefined
+  }
+
+  trackPendingRequest(workspace: T): boolean {
+    if (!workspace.requestId) return false
+    const quarantined = this.pendingRequestIds.get(workspace.requestId)
+    if (quarantined === undefined) return false
+    this.track(workspace)
+    if (quarantined) void this.discardTracked(workspace.id, { retainTombstone: workspace.reused !== true })
+      .finally(() => this.finishRequest(workspace.requestId!))
+    return true
+  }
+
+  release(workspaceId: string): T | undefined {
+    const entry = this.owned.get(workspaceId)
+    if (!entry || "tombstone" in entry || "released" in entry || "completion" in entry) return undefined
+    this.owned.set(workspaceId, { released: true })
+    return entry.workspace
+  }
+
+  get(workspaceId: string): T | undefined {
+    const entry = this.owned.get(workspaceId)
+    return entry && "workspace" in entry && !("completion" in entry) ? entry.workspace : undefined
+  }
+
+  async releaseAfter(workspaceId: string, operation: (workspace: T) => Promise<void>): Promise<T | undefined> {
+    const workspace = this.release(workspaceId)
+    if (!workspace) return undefined
+    try {
+      await operation(workspace)
+      return workspace
+    } catch (error) {
+      const entry = this.owned.get(workspaceId)
+      if (workspace && entry && "released" in entry) this.owned.set(workspaceId, { workspace })
+      throw error
+    }
+  }
+
+  releaseTombstoneForUserCreate(workspaceId: string): void {
+    const entry = this.owned.get(workspaceId)
+    if (entry && ("tombstone" in entry || "released" in entry)) this.owned.delete(workspaceId)
+  }
+
+  owns(workspaceId: string): boolean {
+    const entry = this.owned.get(workspaceId)
+    return Boolean(entry && !("released" in entry))
+  }
+
+  shouldIgnoreEvent(workspaceId: string): boolean {
+    const entry = this.owned.get(workspaceId)
+    return !!entry && ("completion" in entry || "tombstone" in entry)
+  }
+
+  discardCreated(workspace: T, options?: { retainTombstone?: boolean }): Promise<void> {
+    return this.start(workspace, options)
+  }
+
+  discardTracked(workspaceId: string, options?: { retainTombstone?: boolean }): Promise<void> {
+    const entry = this.owned.get(workspaceId)
+    if (!entry || "tombstone" in entry || "released" in entry) return Promise.resolve()
+    if ("completion" in entry) return entry.completion
+    return this.start(entry.workspace, options)
+  }
+
+  private start(workspace: T, options?: { retainTombstone?: boolean }): Promise<void> {
+    const current = this.owned.get(workspace.id)
+    if (current && "completion" in current) return current.completion
+    if (current && ("tombstone" in current || "released" in current)) return Promise.resolve()
+
+    let resolve!: () => void
+    const completion = new Promise<void>((done) => { resolve = done })
+    const entry = { workspace, completion, resolve, retainTombstone: options?.retainTombstone === true }
+    this.owned.set(workspace.id, entry)
+    void this.run(entry)
+    return completion
+  }
+
+  private async run(entry: PendingCleanup<T>): Promise<void> {
+    let lastError: unknown
+    let deleted = false
+    const retryDelays = this.options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS
+    let retryIndex = 0
+
+    try {
+      await retryWithBackoff(() => this.options.discardWorkspace(entry.workspace), {
+        maxAttempts: retryDelays.length + 1,
+        wait: () => (this.options.wait ?? ((delay) => new Promise((resolve) => setTimeout(resolve, delay))))(
+          retryDelays[retryIndex++] ?? 0,
+        ),
+      })
+      deleted = true
+    } catch (error) {
+      lastError = error
+    }
+
+    if (this.owned.get(entry.workspace.id) !== entry) return
+    if (!deleted) {
+      try {
+        this.options.restoreWorkspace(entry.workspace)
+      } catch (error) {
+        lastError = error
+      }
+    }
+    if (deleted && entry.retainTombstone) this.owned.set(entry.workspace.id, { tombstone: true })
+    else this.owned.delete(entry.workspace.id)
+    entry.resolve()
+
+    if (deleted) return
+    try {
+      this.options.onPermanentFailure?.(entry.workspace, lastError)
+    } catch {
+      // Cleanup has already reached its safe terminal state.
+    }
+  }
+}
diff --git a/packages/ui/src/stores/app-session-prompt-hydration.test.ts b/packages/ui/src/stores/app-session-prompt-hydration.test.ts
new file mode 100644
index 00000000..eb8cfbd3
--- /dev/null
+++ b/packages/ui/src/stores/app-session-prompt-hydration.test.ts
@@ -0,0 +1,55 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { createRoot } from "solid-js"
+import { isServer } from "solid-js/web"
+const NO_SESSION_DRAFT_SESSION_ID = "__no_session_draft__"
+describe("app session prompt hydration", () => {
+  it("keeps pasted and image attachments when hydrating a mounted no-session prompt", { skip: isServer }, async () => {
+    const [attachmentsHook, promptHook, attachments, hydration, sessions] = await Promise.all([
+      import("../components/prompt-input/usePromptAttachments.ts"),
+      import("../components/prompt-input/usePromptState.ts"),
+      import("./attachments.ts"),
+      import("./app-session-prompt-hydration.ts"),
+      import("./sessions.ts"),
+    ])
+    const instanceId = "mounted-no-session-instance"
+    let dispose = () => {}, prompt = () => ""
+    createRoot((rootDispose) => {
+      dispose = rootDispose
+      const promptState = promptHook.usePromptState({
+        instanceId: () => instanceId,
+        sessionId: () => NO_SESSION_DRAFT_SESSION_ID,
+        instanceFolder: () => "",
+      })
+      prompt = promptState.prompt; attachmentsHook.usePromptAttachments({
+        instanceId: () => instanceId,
+        sessionId: () => NO_SESSION_DRAFT_SESSION_ID,
+        instanceFolder: () => "/work",
+        prompt: promptState.prompt,
+        setPrompt: promptState.setPrompt,
+        getTextarea: () => null,
+      })
+    })
+    try {
+      hydration.hydrateWorkspacePromptState(instanceId, {
+        drafts: {
+          [NO_SESSION_DRAFT_SESSION_ID]: "before [pasted #1] and [Image #1] after",
+          "ordinary-session": "ordinary draft",
+        },
+        attachments: { [NO_SESSION_DRAFT_SESSION_ID]: [
+          { id: "paste-1", type: "text", display: "pasted #1 (4 lines)", url: "", filename: "paste-1.txt", mediaType: "text/plain", source: { type: "text", value: "restored pasted text" } },
+          { id: "image-1", type: "file", display: "[Image #1]", url: "", filename: "image-1.png", mediaType: "image/png", source: { type: "file", path: "/work/image-1.png", mime: "image/png" } },
+        ] },
+      }, new Set(["ordinary-session"]), NO_SESSION_DRAFT_SESSION_ID)
+      assert.equal(prompt(), "before [pasted #1] and [Image #1] after")
+      assert.deepEqual(attachments.getAttachments(instanceId, NO_SESSION_DRAFT_SESSION_ID).map(({ id }) => id), ["paste-1", "image-1"])
+      assert.equal(sessions.getSessionDraftPrompt(instanceId, "ordinary-session"), "ordinary draft")
+      assert.equal(sessions.getAuthoritativeDraftSessionIdsForInstance(instanceId).has("ordinary-session"), false)
+      sessions.clearSessionDraftPrompt(instanceId, "ordinary-session")
+      assert.equal(sessions.getSessionDraftPrompt(instanceId, "ordinary-session"), "")
+      assert.equal(sessions.getAuthoritativeDraftSessionIdsForInstance(instanceId).has("ordinary-session"), true)
+    } finally {
+      dispose(); attachments.clearInstanceAttachments(instanceId); sessions.clearInstanceDraftPrompts(instanceId)
+    }
+  })
+})
diff --git a/packages/ui/src/stores/app-session-prompt-hydration.ts b/packages/ui/src/stores/app-session-prompt-hydration.ts
new file mode 100644
index 00000000..a30ce961
--- /dev/null
+++ b/packages/ui/src/stores/app-session-prompt-hydration.ts
@@ -0,0 +1,35 @@
+import { batch } from "solid-js"
+import type { RestorableWorkspaceTabState } from "./client-state-codec"
+import { hydrateRestorableAttachment } from "./client-state-attachments-codec"
+import { getAuthoritativeAttachmentSessionIdsForInstance, hydrateSessionAttachments } from "./attachments"
+import { getAuthoritativeDraftSessionIdsForInstance, hydrateSessionDraftPrompt } from "./sessions"
+
+export function hydrateWorkspacePromptState(
+  instanceId: string,
+  snapshot: Pick<RestorableWorkspaceTabState, "drafts" | "attachments">,
+  validSessionIds: ReadonlySet<string>,
+  noSessionDraftSessionId: string,
+): void {
+  const canHydrate = (sessionId: string) =>
+    validSessionIds.has(sessionId) || sessionId === noSessionDraftSessionId
+  const authoritativeDrafts = getAuthoritativeDraftSessionIdsForInstance(instanceId)
+  const authoritativeAttachments = getAuthoritativeAttachmentSessionIdsForInstance(instanceId)
+
+  batch(() => {
+    // Mounted prompt synchronization requires placeholders to exist before attachments publish.
+    for (const [sessionId, draft] of Object.entries(snapshot.drafts)) {
+      if (!draft || !canHydrate(sessionId)) continue
+      if (authoritativeDrafts.has(sessionId)) continue
+      hydrateSessionDraftPrompt(instanceId, sessionId, draft)
+    }
+    for (const [sessionId, attachments] of Object.entries(snapshot.attachments)) {
+      if (!canHydrate(sessionId)) continue
+      if (authoritativeAttachments.has(sessionId)) continue
+      hydrateSessionAttachments(
+        instanceId,
+        sessionId,
+        attachments.map(hydrateRestorableAttachment).filter((value) => value !== null),
+      )
+    }
+  })
+}
diff --git a/packages/ui/src/stores/app-session-reconciliation.test.ts b/packages/ui/src/stores/app-session-reconciliation.test.ts
new file mode 100644
index 00000000..f8b7534c
--- /dev/null
+++ b/packages/ui/src/stores/app-session-reconciliation.test.ts
@@ -0,0 +1,72 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { getUnavailableRestoredSessionIds, getUnavailableWorkspaceIds, reconcileWorkspaceTabs, resolveRestoredActiveTabId, resolveRestoredSessionSelection, shouldRestoreSessionState } from "./app-session-reconciliation.ts"
+describe("app session reconciliation", () => {
+  const workspaceCases = [
+    ["matches duplicate workspace folders by normalized path occurrence", [
+      { kind: "workspace" as const, folderPath: String.raw`C:\Code\Nomad`, occurrence: 1 }, { kind: "workspace" as const, folderPath: "c:/code/nomad/", occurrence: 0 },
+    ], [{ id: "first", folderPath: "C:/CODE/NOMAD" }, { id: "second", folderPath: "c:\\code\\nomad\\" }], ["second", "first"]],
+    ["derives occurrences for snapshots written before occurrence was explicit", [
+      { kind: "workspace" as const, folderPath: "/code/nomad" }, { kind: "workspace" as const, folderPath: "/code/nomad/" },
+    ], [{ id: "first", folderPath: "/code/nomad" }, { id: "second", folderPath: "/code/nomad" }], ["first", "second"]],
+    ["does not match one live workspace to duplicate descriptors", [
+      { kind: "workspace" as const, folderPath: "/code/nomad", occurrence: 0 }, { kind: "workspace" as const, folderPath: "/code/nomad", occurrence: 0 },
+    ], [{ id: "only", folderPath: "/code/nomad" }], ["only", null]],
+  ] as const
+  for (const [label, saved, live, expected] of workspaceCases) it(label, () => assert.deepEqual(
+    reconcileWorkspaceTabs([...saved], [...live]).map(({ existingWorkspaceId }) => existingWorkspaceId), expected,
+  ))
+  it("keeps saved order while a restored workspace is still starting", () => {
+    const saved = [
+      { kind: "workspace", folderPath: "D:/DreamX-World" },
+      { kind: "workspace", folderPath: "D:/CodeNomad" },
+      { kind: "workspace", folderPath: "D:/stale" },
+    ]
+    const live = [
+      { id: "codenomad", folderPath: "D:/CodeNomad", status: "ready" },
+      { id: "dreamx", folderPath: "D:/DreamX-World", status: "starting" },
+      { id: "stale", folderPath: "D:/stale", status: "stopped" },
+    ] as const
+
+    assert.deepEqual(
+      reconcileWorkspaceTabs(saved, live).map(({ existingWorkspaceId }) => existingWorkspaceId),
+      ["dreamx", "codenomad", null],
+    )
+  })
+  it("reconciles only workspaces missing from a refresh and not owned by restore cleanup", () => {
+    assert.deepEqual(
+      getUnavailableWorkspaceIds(["present", "stopped", "cancelling"], new Set(["present"]), (id) => id === "cancelling"),
+      ["stopped"],
+    )
+  })
+  const selectionCases = [
+    ["falls back to a valid parent when the active session is stale", [{ id: "parent", parentId: null }, { id: "child", parentId: "parent" }], "parent", "deleted-child", { parentSessionId: "parent", activeSessionId: "parent" }],
+    ["restores a grandchild under its root session", [{ id: "root", parentId: null }, { id: "child", parentId: "root" }, { id: "grandchild", parentId: "child" }], "root", "grandchild", { parentSessionId: "root", activeSessionId: "grandchild" }],
+    ["keeps the special info selection without requiring a session", [], null, "info", { parentSessionId: null, activeSessionId: "info" }],
+  ] as const
+  for (const [label, sessions, parent, active, expected] of selectionCases) it(label, () => assert.deepEqual(
+    resolveRestoredSessionSelection([...sessions], parent, active), expected,
+  ))
+  it("rejects ancestry with a cycle or missing parent", () => {
+    assert.equal(resolveRestoredSessionSelection([{ id: "first", parentId: "second" }, { id: "second", parentId: "first" }], null, "first"), null)
+    assert.equal(resolveRestoredSessionSelection([{ id: "orphan", parentId: "missing" }], null, "orphan"), null)
+  })
+  it("treats missing saved session references as unsafe", () => {
+    const sessions = [{ id: "loaded", parentId: null }]
+    const unavailable = (state: Parameters<typeof getUnavailableRestoredSessionIds>[1], allowed: string[] = []) => [...getUnavailableRestoredSessionIds(sessions, state, allowed)]
+    assert.deepEqual(unavailable({ activeParentSessionId: "loaded", activeSessionId: "info", draftSessionIds: ["loaded", "__no_session_draft__"], attachmentSessionIds: ["loaded"], scrollSessionIds: ["loaded"] }, ["__no_session_draft__"]), [])
+    assert.notEqual(unavailable({ activeParentSessionId: "missing-parent", activeSessionId: "missing-active", draftSessionIds: ["missing-draft"], attachmentSessionIds: ["missing-attachment"], scrollSessionIds: ["missing-scroll"] }).length, 0)
+    assert.deepEqual(unavailable({ activeSessionId: "missing-active", draftSessionIds: ["missing-draft"], attachmentSessionIds: ["missing-attachment"], scrollSessionIds: ["loaded"] }), ["missing-active", "missing-draft", "missing-attachment"])
+    assert.deepEqual(unavailable({ draftSessionIds: [], scrollSessionIds: [], expandedSessionIds: ["loaded", "later"] }), ["later"])
+  })
+
+  it("falls back to the first restored tab when the active SideCar failed", () => {
+    assert.equal(resolveRestoredActiveTabId(["instance:workspace", null, "sidecar:other"], 1), "instance:workspace")
+  })
+  it("does not restore for secondary or disabled clients", () => {
+    const snapshot = { tabs: [] }
+    for (const [primary, enabled, state, expected] of [[false, true, snapshot, false], [true, false, snapshot, false], [true, true, null, false], [true, true, snapshot, true]] as const) {
+      assert.equal(shouldRestoreSessionState(primary, enabled, state), expected)
+    }
+  })
+})
diff --git a/packages/ui/src/stores/app-session-reconciliation.ts b/packages/ui/src/stores/app-session-reconciliation.ts
new file mode 100644
index 00000000..aaa69589
--- /dev/null
+++ b/packages/ui/src/stores/app-session-reconciliation.ts
@@ -0,0 +1,109 @@
+export type ReconcileTabDescriptor = { kind: string; folderPath?: string; occurrence?: number }
+type LiveWorkspaceDescriptor = { id: string; folderPath: string; status?: string }
+export type SessionDescriptor = { id: string; parentId?: string | null }
+export interface RestoredSessionReferences {
+  activeParentSessionId?: string
+  activeSessionId?: string
+  draftSessionIds: readonly string[]
+  attachmentSessionIds?: readonly string[]
+  scrollSessionIds: readonly string[]
+  idleMarkerSessionIds?: readonly string[]
+  generationRecoverySessionIds?: readonly string[]
+  expandedSessionIds?: readonly string[]
+}
+export function normalizeWorkspacePath(folderPath: string): string {
+  const windowsLike = /^(?:[A-Za-z]:[/\\]|[/\\]{2})/.test(folderPath)
+  const normalized = windowsLike ? folderPath.replace(/\\/g, "/").toLowerCase() : folderPath
+  return normalized === "/" || /^[a-z]:\/$/.test(normalized) ? normalized : normalized.replace(/\/+$/, "")
+}
+export function getUnavailableWorkspaceIds(
+  localIds: Iterable<string>,
+  remoteIds: ReadonlySet<string>,
+  isProtected: (id: string) => boolean,
+): string[] {
+  return [...localIds].filter((id) => !remoteIds.has(id) && !isProtected(id))
+}
+export function reconcileWorkspaceTabs(
+  tabs: readonly ReconcileTabDescriptor[],
+  liveWorkspaces: readonly LiveWorkspaceDescriptor[],
+) {
+  const liveByPath = new Map<string, LiveWorkspaceDescriptor[]>()
+  for (const workspace of liveWorkspaces) {
+    if (workspace.status === "stopped" || workspace.status === "error") continue
+    const path = normalizeWorkspacePath(workspace.folderPath)
+    liveByPath.set(path, [...(liveByPath.get(path) ?? []), workspace])
+  }
+  const nextOccurrences = new Map<string, number>()
+  const claimed = new Set<string>()
+  return tabs.flatMap((tab, tabIndex) => {
+    if (tab.kind !== "workspace" || typeof tab.folderPath !== "string") return []
+    const path = normalizeWorkspacePath(tab.folderPath)
+    const inferred = nextOccurrences.get(path) ?? 0
+    const occurrence = Number.isInteger(tab.occurrence) && Number(tab.occurrence) >= 0 ? Number(tab.occurrence) : inferred
+    nextOccurrences.set(path, Math.max(inferred, occurrence) + 1)
+    const workspace = liveByPath.get(path)?.[occurrence]
+    const existingWorkspaceId = workspace && !claimed.has(workspace.id) ? workspace.id : null
+    if (existingWorkspaceId) claimed.add(existingWorkspaceId)
+    return [{
+      tabIndex,
+      descriptor: { kind: "workspace" as const, folderPath: tab.folderPath, occurrence },
+      existingWorkspaceId,
+    }]
+  })
+}
+export function resolveRestoredSessionSelection(
+  availableSessions: readonly SessionDescriptor[],
+  requestedParentSessionId: string | null | undefined,
+  requestedActiveSessionId: string | null | undefined,
+) {
+  const sessions = new Map(availableSessions.map((session) => [session.id, session]))
+  const rootId = (sessionId: string | null | undefined): string | null => {
+    let current = sessionId ? sessions.get(sessionId) : undefined
+    const seen = new Set<string>()
+    while (current?.parentId) {
+      if (seen.has(current.id)) return null
+      seen.add(current.id)
+      current = sessions.get(current.parentId)
+    }
+    return current?.id ?? null
+  }
+  const parentSessionId = rootId(requestedParentSessionId)
+  if (requestedActiveSessionId === "info") return { parentSessionId, activeSessionId: "info" }
+  const active = requestedActiveSessionId ? sessions.get(requestedActiveSessionId) : undefined
+  const activeParentId = rootId(active?.id)
+  if (active && activeParentId && (!parentSessionId || parentSessionId === activeParentId)) {
+    return { parentSessionId: activeParentId, activeSessionId: active.id }
+  }
+  return parentSessionId ? { parentSessionId, activeSessionId: parentSessionId } : null
+}
+export function getUnavailableRestoredSessionIds(
+  availableSessions: readonly SessionDescriptor[],
+  references: RestoredSessionReferences,
+  allowedNonSessionIds: readonly string[] = [],
+): Set<string> {
+  const available = new Set(availableSessions.map(({ id }) => id))
+  const allowed = new Set(allowedNonSessionIds)
+  const referenced = [
+    references.activeParentSessionId,
+    references.activeSessionId === "info" ? undefined : references.activeSessionId,
+    ...references.draftSessionIds,
+    ...(references.attachmentSessionIds ?? []),
+    ...references.scrollSessionIds,
+    ...(references.idleMarkerSessionIds ?? []),
+    ...(references.generationRecoverySessionIds ?? []),
+    ...(references.expandedSessionIds ?? []),
+  ]
+  return new Set(referenced.filter((id): id is string => Boolean(id) && !available.has(id!) && !allowed.has(id!)))
+}
+export function resolveRestoredActiveTabId(
+  restoredTabIds: readonly (string | null | undefined)[],
+  requestedActiveTabIndex: number,
+): string | null {
+  const requested = Number.isInteger(requestedActiveTabIndex) && requestedActiveTabIndex >= 0
+    ? restoredTabIds[requestedActiveTabIndex]
+    : null
+  return requested || restoredTabIds.find((id): id is string => Boolean(id)) || null
+}
+export function shouldRestoreSessionState(isPrimary: boolean, restoreEnabled: boolean, snapshot: unknown): boolean {
+  return Boolean(isPrimary && restoreEnabled && snapshot)
+}
diff --git a/packages/ui/src/stores/app-session-restore-gate.test.ts b/packages/ui/src/stores/app-session-restore-gate.test.ts
new file mode 100644
index 00000000..66279b33
--- /dev/null
+++ b/packages/ui/src/stores/app-session-restore-gate.test.ts
@@ -0,0 +1,19 @@
+import assert from "node:assert/strict"
+import { it } from "node:test"
+
+import { shouldShowAppHomeOverlay, shouldShowEmptyAppHome } from "./app-session-restore-gate.ts"
+
+const tab = { kind: "sidecar" as const, sidecarId: "preview" }
+
+it("hides the empty-app home while saved tabs are restoring", () => {
+  assert.equal(shouldShowEmptyAppHome({ tabs: [tab], activeTabIndex: 0 }, true), false)
+  assert.equal(shouldShowEmptyAppHome({ tabs: [tab], activeTabIndex: 0, homeActive: true }, true), true)
+  assert.equal(shouldShowEmptyAppHome({ tabs: [], activeTabIndex: -1 }, true), true)
+  assert.equal(shouldShowEmptyAppHome({ tabs: [tab], activeTabIndex: 0 }, false), true)
+})
+
+it("mounts the requested home overlay only when tabs exist", () => {
+  assert.equal(shouldShowAppHomeOverlay(true, 0), false)
+  assert.equal(shouldShowAppHomeOverlay(true, 1), true)
+  assert.equal(shouldShowAppHomeOverlay(false, 1), false)
+})
diff --git a/packages/ui/src/stores/app-session-restore-gate.ts b/packages/ui/src/stores/app-session-restore-gate.ts
new file mode 100644
index 00000000..8b0d16e4
--- /dev/null
+++ b/packages/ui/src/stores/app-session-restore-gate.ts
@@ -0,0 +1,18 @@
+import { createSignal } from "solid-js"
+import type { RestorableSessionState } from "./client-state-codec"
+
+const [appSessionRestoreGateActive, setAppSessionRestoreGateActive] = createSignal(true)
+
+function releaseAppSessionRestoreGate(): void {
+  setAppSessionRestoreGateActive(false)
+}
+
+function shouldShowEmptyAppHome(snapshot: RestorableSessionState | null, restoreActive = appSessionRestoreGateActive()): boolean {
+  return !restoreActive || !snapshot?.tabs.length || snapshot.homeActive === true
+}
+
+function shouldShowAppHomeOverlay(requested: boolean, tabCount: number): boolean {
+  return requested && tabCount > 0
+}
+
+export { appSessionRestoreGateActive, releaseAppSessionRestoreGate, shouldShowAppHomeOverlay, shouldShowEmptyAppHome }
diff --git a/packages/ui/src/stores/app-session-restore-queue.test.ts b/packages/ui/src/stores/app-session-restore-queue.test.ts
new file mode 100644
index 00000000..29119fb0
--- /dev/null
+++ b/packages/ui/src/stores/app-session-restore-queue.test.ts
@@ -0,0 +1,39 @@
+import assert from "node:assert/strict"
+import { it } from "node:test"
+import { runWithSerializedCommits } from "./app-session-restore-queue.ts"
+
+function deferred() {
+  let resolve!: () => void
+  const promise = new Promise<void>((done) => { resolve = done })
+  return { promise, resolve }
+}
+
+it("starts create requests concurrently but commits mounts in saved order", async () => {
+  const requests = [deferred(), deferred(), deferred()]
+  const hydrations = [deferred(), deferred(), deferred()]
+  const started: number[] = []
+  const commits: number[] = []
+  let mounted = 0
+  const restoration = runWithSerializedCommits([0, 1, 2], async (index, waitForCommit, finishCommit) => {
+    started.push(index)
+    await requests[index]!.promise
+    await waitForCommit
+    mounted += 1
+    assert.equal(mounted, 1, "workspace mounts never overlap")
+    commits.push(index)
+    await Promise.resolve()
+    mounted -= 1
+    finishCommit()
+    await hydrations[index]!.promise
+  })
+
+  assert.deepEqual(started, [0, 1, 2], "all network requests start without waiting for a prior mount")
+  requests[2]!.resolve(); requests[1]!.resolve()
+  await Promise.resolve()
+  assert.deepEqual(commits, [], "later responses wait for their saved-order commit turn")
+  requests[0]!.resolve()
+  await new Promise<void>((resolve) => setImmediate(resolve))
+  assert.deepEqual(commits, [0, 1, 2], "post-mount hydration does not hold the commit queue")
+  hydrations.forEach(({ resolve }) => resolve())
+  await restoration
+})
diff --git a/packages/ui/src/stores/app-session-restore-queue.ts b/packages/ui/src/stores/app-session-restore-queue.ts
new file mode 100644
index 00000000..095f8442
--- /dev/null
+++ b/packages/ui/src/stores/app-session-restore-queue.ts
@@ -0,0 +1,15 @@
+export async function runWithSerializedCommits<T>(
+  items: readonly T[],
+  run: (item: T, waitForCommit: Promise<void>, finishCommit: () => void) => Promise<void>,
+): Promise<void> {
+  let previous = Promise.resolve()
+  const tasks = items.map((item) => {
+    const waitForCommit = previous
+    let finishCommit!: () => void
+    const commit = new Promise<void>((resolve) => { finishCommit = resolve })
+    const task = run(item, waitForCommit, finishCommit).finally(finishCommit)
+    previous = Promise.allSettled([waitForCommit, commit]).then(() => undefined)
+    return task
+  })
+  await Promise.all(tasks)
+}
diff --git a/packages/ui/src/stores/app-session-restore-timeout.test.ts b/packages/ui/src/stores/app-session-restore-timeout.test.ts
new file mode 100644
index 00000000..fc97aa36
--- /dev/null
+++ b/packages/ui/src/stores/app-session-restore-timeout.test.ts
@@ -0,0 +1,53 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { RestoreTimeoutError, runAbortable } from "./app-session-restore-timeout.ts"
+const deferred = () => {
+  let resolve!: () => void
+  const promise = new Promise<void>((done) => { resolve = done })
+  return { promise, resolve }
+}
+const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0))
+describe("app session restore timeouts", () => {
+  it("rejects an operation that does not settle within its bound", async () => {
+    let operationSignal: AbortSignal | undefined
+    await assert.rejects(runAbortable((signal) => {
+      operationSignal = signal; return new Promise<never>(() => {})
+    }, { timeoutMs: 5, message: "restore stalled" }), (error) => error instanceof RestoreTimeoutError && error.message === "restore stalled")
+    assert.equal(operationSignal?.aborted, true)
+  })
+  it("deactivates a timed-out restore before its late completion", async () => {
+    const pending = deferred()
+    let lateWrite = false
+    await assert.rejects(runAbortable(async (signal) => {
+      await pending.promise
+      if (!signal.aborted) lateWrite = true
+    }, { timeoutMs: 5, message: "startup restore stalled" }), RestoreTimeoutError)
+    pending.resolve()
+    await tick()
+    assert.equal(lateWrite, false)
+  })
+  it("propagates a deadline abort signal into a nested operation", async () => {
+    let nestedSignal: AbortSignal | undefined
+    await assert.rejects(runAbortable((deadlineSignal) => runAbortable((signal) => {
+      nestedSignal = signal; return new Promise<never>(() => {})
+    }, { timeoutMs: 1000, message: "nested stalled", signal: deadlineSignal }), { timeoutMs: 5, message: "deadline stalled" }), RestoreTimeoutError)
+    assert.equal(nestedSignal?.aborted, true)
+  })
+  it("cancels the restore deadline when its owner is disposed", async () => {
+    const controller = new AbortController()
+    let restoreSignal: AbortSignal | undefined
+    const completion = runAbortable(async (signal) => {
+      restoreSignal = signal; await new Promise<never>(() => undefined)
+    }, { timeoutMs: 1_000, message: "deadline stalled", signal: controller.signal })
+    controller.abort(new Error("restore disposed"))
+    await assert.rejects(completion, /restore disposed/)
+    assert.equal(restoreSignal?.aborted, true)
+  })
+  it("rejects a SideCar load that completes after its restore signal aborts", async () => {
+    const load = deferred()
+    const controller = new AbortController()
+    const completion = runAbortable(() => load.promise, { signal: controller.signal })
+    controller.abort(new Error("SideCar restore timed out")); load.resolve()
+    await assert.rejects(completion, /SideCar restore timed out/)
+  })
+})
diff --git a/packages/ui/src/stores/app-session-restore-timeout.ts b/packages/ui/src/stores/app-session-restore-timeout.ts
new file mode 100644
index 00000000..ea6e7008
--- /dev/null
+++ b/packages/ui/src/stores/app-session-restore-timeout.ts
@@ -0,0 +1,55 @@
+export class RestoreTimeoutError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "RestoreTimeoutError"
+  }
+}
+
+export function getAbortReason(signal: AbortSignal): Error {
+  if (signal.reason instanceof Error) return signal.reason
+  const error = new Error("Restore operation was aborted")
+  error.name = "AbortError"
+  return error
+}
+
+export function runAbortable<T>(
+  operation: (signal: AbortSignal) => Promise<T>,
+  options: { signal?: AbortSignal; timeoutMs?: number; message?: string } = {},
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const controller = new AbortController()
+    let settled = false
+    const finish = (callback: () => void) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      options.signal?.removeEventListener("abort", handleParentAbort)
+      callback()
+    }
+    const handleParentAbort = () => {
+      const reason = getAbortReason(options.signal!)
+      controller.abort(reason)
+      finish(() => reject(reason))
+    }
+    const timer = options.timeoutMs === undefined ? undefined : setTimeout(() => {
+      const error = new RestoreTimeoutError(options.message ?? "Operation timed out")
+      controller.abort(error)
+      finish(() => reject(error))
+    }, options.timeoutMs)
+
+    if (options.signal?.aborted) {
+      handleParentAbort()
+      return
+    }
+    options.signal?.addEventListener("abort", handleParentAbort, { once: true })
+
+    Promise.resolve().then(() => operation(controller.signal)).then(
+      (value) => {
+        finish(() => resolve(value))
+      },
+      (error) => {
+        finish(() => reject(error))
+      },
+    )
+  })
+}
diff --git a/packages/ui/src/stores/app-session-snapshot-merge.test.ts b/packages/ui/src/stores/app-session-snapshot-merge.test.ts
new file mode 100644
index 00000000..d2f24c8b
--- /dev/null
+++ b/packages/ui/src/stores/app-session-snapshot-merge.test.ts
@@ -0,0 +1,550 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import type { RestorableAttachment } from "./client-state-attachments-codec.ts"
+import type { RestorableSessionState, RestorableWorkspaceTabState } from "./client-state-codec.ts"
+import {
+  createRestorableSessionPreservation,
+  createRestoredTabCommitGuard,
+  getPreservedWorkspaceState,
+  getPreservedWorkspaceReopenTarget,
+  hasRestoredTabBinding,
+  markPreservedWorkspaceRemoved,
+  markPreservedWorkspaceReopened,
+  markPreservedWorkspaceUnavailable,
+  mergeRestorableSessionState,
+  recordRestoredTab,
+  settleRestoredTab,
+  type RestorableSessionPreservation,
+  type RestorableWorkspaceRuntimeAuthority,
+} from "./app-session-snapshot-merge.ts"
+import { reconcileWorkspaceTabs } from "./app-session-reconciliation.ts"
+
+const empty = (): RestorableSessionState => ({ tabs: [], activeTabIndex: -1 })
+const session = (
+  tabs: RestorableSessionState["tabs"],
+  activeTabIndex = tabs.length ? 0 : -1,
+): RestorableSessionState => ({ tabs, activeTabIndex })
+const workspace = (
+  folder: string,
+  occurrence = 0,
+  state: Partial<RestorableWorkspaceTabState> = {},
+): RestorableWorkspaceTabState => ({
+  kind: "workspace", folder, occurrence, drafts: {}, attachments: {}, scrollSnapshots: {},
+  unseenIdleSince: {}, generationRecovery: {}, ...state,
+})
+const sidecar = (sidecarId: string) => ({ kind: "sidecar" as const, sidecarId })
+const attachment = (id = "paste", path?: string): RestorableAttachment => ({
+  id, type: path ? "file" : "text", display: id, url: "", filename: `${id}.txt`, mediaType: "text/plain",
+  source: path ? { type: "file", path, mime: "text/plain" } : { type: "text", value: `${id} content` },
+})
+const scroll = (scrollTop: number, updatedAt = 1) => ({ scrollTop, atBottom: false, updatedAt })
+
+function restored(
+  saved: RestorableSessionState,
+  mappings: readonly { source: number; runtime?: string | null; unavailable?: readonly string[]; pending?: boolean }[] = [],
+): RestorableSessionPreservation {
+  const preservation = createRestorableSessionPreservation(saved)
+  for (const mapping of mappings) {
+    recordRestoredTab(
+      preservation,
+      mapping.source,
+      mapping.runtime ?? null,
+      mapping.pending ? undefined : new Set(mapping.unavailable),
+    )
+  }
+  return preservation
+}
+
+function workspaceAt(state: RestorableSessionState, index = 0): RestorableWorkspaceTabState {
+  const tab = state.tabs[index]
+  assert.equal(tab?.kind, "workspace", `tab ${index} should be a workspace`)
+  if (tab?.kind !== "workspace") throw new Error(`tab ${index} is not a workspace`)
+  return tab
+}
+
+const labels = (state: RestorableSessionState) => state.tabs.map((tab) =>
+  tab.kind === "workspace" ? `${tab.folder}:${tab.occurrence}` : tab.sidecarId)
+const mergeOne = (
+  savedTab: RestorableWorkspaceTabState,
+  currentTab = workspace(savedTab.folder, savedTab.occurrence),
+  authority?: RestorableWorkspaceRuntimeAuthority,
+) => workspaceAt(mergeRestorableSessionState(
+  session([currentTab]),
+  createRestorableSessionPreservation(session([savedTab])),
+  { currentTabIds: ["instance:work"], currentTabAuthorities: [authority] },
+))
+
+describe("app session snapshot merge", () => {
+  it("retains the latest restored tab state after a non-authoritative stop", () => {
+    const saved = session([workspace("/work", 0, { drafts: { missing: "saved", current: "old" } })])
+    const preservation = restored(saved, [{ source: 0, runtime: "instance:work" }])
+    markPreservedWorkspaceUnavailable(
+      preservation,
+      { runtimeTabId: "instance:work", folder: "/work", occurrence: 0 },
+      workspace("/work", 0, { drafts: { current: "latest unsent draft" } }),
+    )
+    const merged = mergeRestorableSessionState(empty(), preservation, { currentTabIds: [] })
+    assert.deepEqual(workspaceAt(merged).drafts, { missing: "saved", current: "latest unsent draft" })
+    assert.equal(getPreservedWorkspaceState(
+      preservation,
+      { runtimeTabId: "instance:other", folder: "/work", occurrence: 0 },
+    ), null, "a different runtime cannot claim prompts by folder occurrence alone")
+  })
+
+  it("retains missing sessions, transient tabs, and new runtime tabs", () => {
+    const savedFile = attachment("path-file", "/work/a/notes.txt")
+    const saved = session([
+      workspace("/work/a", 0, {
+        activeParentSessionId: "missing", activeSessionId: "missing",
+        drafts: { missing: "saved draft" }, attachments: { missing: [savedFile] },
+        scrollSnapshots: { missing: scroll(42) },
+      }),
+      sidecar("transient"), sidecar("deleted"), workspace("/work/b"),
+    ], 1)
+    const preservation = restored(saved, [
+      { source: 0, unavailable: ["missing"] }, { source: 2 }, { source: 3 },
+    ])
+    const merged = mergeRestorableSessionState(session([
+      workspace("/work/a", 0, { drafts: { visible: "current draft" } }),
+      workspace("/work/b"), sidecar("new-runtime-tab"),
+    ], 2), preservation)
+
+    assert.deepEqual(labels(merged), ["/work/a:0", "transient", "/work/b:0", "new-runtime-tab"])
+    assert.equal(merged.activeTabIndex, 3)
+    const tab = workspaceAt(merged)
+    assert.deepEqual(tab.drafts, { missing: "saved draft", visible: "current draft" })
+    assert.deepEqual(tab.attachments.missing, [savedFile], "path-backed payload survives")
+    assert.deepEqual(tab.scrollSnapshots.missing, scroll(42), "missing-session scroll is seeded")
+    assert.deepEqual([tab.activeParentSessionId, tab.activeSessionId], ["missing", "missing"])
+  })
+
+  it("backfills failed hydration without replacing current metadata or user mutations", () => {
+    const savedFile = attachment("paste")
+    const saved = session([
+      workspace("/failed", 0, {
+        projectName: "saved metadata", activeParentSessionId: "unsaved", activeSessionId: "unsaved",
+        drafts: { unsaved: "[paste]", live: "stale" }, attachments: { unsaved: [savedFile] },
+        scrollSnapshots: { unsaved: scroll(37) },
+      }),
+      workspace("/restored"),
+    ])
+    const merged = mergeRestorableSessionState(
+      session([workspace("/restored"), workspace("/failed", 0, {
+        projectName: "current metadata", drafts: { live: "current draft" },
+      })]),
+      restored(saved, [{ source: 1, runtime: "instance:restored" }]),
+      { currentTabIds: ["instance:restored", "instance:failed"] },
+    )
+
+    assert.deepEqual(labels(merged), ["/restored:0", "/failed:0"])
+    const tab = workspaceAt(merged, 1)
+    assert.equal(tab.projectName, "current metadata")
+    assert.deepEqual(tab.drafts, { unsaved: "[paste]", live: "current draft" })
+    assert.deepEqual(tab.attachments.unsaved, [savedFile])
+    assert.equal(tab.scrollSnapshots.unsaved?.scrollTop, 37)
+    assert.deepEqual([tab.activeParentSessionId, tab.activeSessionId], ["unsaved", "unsaved"])
+  })
+
+  it("retains payload records at persistence budget boundaries", () => {
+    const drafts = Object.fromEntries(Array.from({ length: 24 }, (_, index) => [`draft-${index}`, `value-${index}`]))
+    const scrollSnapshots = Object.fromEntries(Array.from({ length: 96 }, (_, index) => [`scroll-${index}`, scroll(index)]))
+    const tab = mergeOne(workspace("/budget", 0, {
+      drafts, scrollSnapshots, attachments: { path: [attachment("large-path", "/budget/large.bin")] },
+    }))
+    assert.equal(Object.keys(tab.drafts).length, 24, "draft limit remains intact")
+    assert.equal(Object.keys(tab.scrollSnapshots).length, 96, "per-tab scroll limit remains intact")
+    assert.equal(tab.attachments.path?.[0]?.source.type, "file", "path payload remains intact")
+  })
+
+  for (const testCase of [
+    { label: "draft cleared by user", field: "drafts" as const, saved: { missing: "saved" }, owned: "missing" },
+    { label: "last attachment removed", field: "attachments" as const, saved: { missing: [attachment()] }, owned: "missing" },
+    { label: "idle marker seen", field: "unseenIdleSince" as const, saved: { seen: 1_000 }, authority: "idleMarkers" as const, owned: "seen" },
+    { label: "generation recovery cleared", field: "generationRecovery" as const, saved: { resumed: "working" as const }, owned: "resumed" },
+  ]) {
+    it(`does not resurrect preserved state after authoritative ${testCase.label}`, () => {
+      const authorityField = testCase.authority ?? testCase.field
+      const tab = mergeOne(
+        workspace("/work", 0, { [testCase.field]: testCase.saved }),
+        workspace("/work"),
+        { [authorityField]: new Set([testCase.owned]) },
+      )
+      assert.deepEqual(tab[testCase.field], {}, `${testCase.field} should remain cleared`)
+    })
+  }
+
+  it("removes every record and selection for a remotely deleted session", () => {
+    const tab = mergeOne(workspace("/work", 0, {
+      activeParentSessionId: "deleted", activeSessionId: "deleted", drafts: { deleted: "draft" },
+      attachments: { deleted: [attachment()] }, scrollSnapshots: { deleted: scroll(42) },
+      unseenIdleSince: { deleted: 1_000 }, generationRecovery: { deleted: "working" },
+    }), workspace("/work"), { deletedSessions: new Set(["deleted"]) })
+    assert.deepEqual({
+      drafts: tab.drafts, attachments: tab.attachments, scrolls: tab.scrollSnapshots,
+      idle: tab.unseenIdleSince, recovery: tab.generationRecovery,
+    }, { drafts: {}, attachments: {}, scrolls: {}, idle: {}, recovery: {} })
+    assert.deepEqual([tab.activeParentSessionId, tab.activeSessionId], [undefined, undefined])
+  })
+
+  it("preserves only unavailable idle and recovery records after partial restore", () => {
+    const saved = session([workspace("/work", 0, {
+      unseenIdleSince: { missing: 1_000, loaded: 2_000 },
+      generationRecovery: { missing: "working", loaded: "interrupted" },
+    })])
+    const merged = mergeRestorableSessionState(
+      session([workspace("/work")]),
+      restored(saved, [{ source: 0, runtime: "instance:work", unavailable: ["missing"] }]),
+      { currentTabIds: ["instance:work"], currentTabAuthorities: [{
+        idleMarkers: new Set(["loaded"]), generationRecovery: new Set(["loaded"]),
+      }] },
+    )
+    const tab = workspaceAt(merged)
+    assert.deepEqual(tab.unseenIdleSince, { missing: 1_000 })
+    assert.deepEqual(tab.generationRecovery, { missing: "working" })
+  })
+
+  it("keeps all authoritative current nested values over preserved values", () => {
+    const tab = mergeOne(
+      workspace("/work", 0, {
+        drafts: { id: "saved" }, attachments: { id: [attachment("saved")] },
+        scrollSnapshots: { id: scroll(10) }, generationRecovery: { id: "working" },
+      }),
+      workspace("/work", 0, {
+        drafts: { id: "current" }, attachments: { id: [attachment("current")] },
+        scrollSnapshots: { id: scroll(90, 2) }, generationRecovery: { id: "interrupted" },
+      }),
+      { drafts: new Set(["id"]), attachments: new Set(["id"]), scrollSnapshots: new Set(["id"]),
+        generationRecovery: new Set(["id"]) },
+    )
+    assert.equal(tab.drafts.id, "current")
+    assert.equal(tab.attachments.id?.[0]?.id, "current")
+    assert.equal(tab.scrollSnapshots.id?.scrollTop, 90)
+    assert.equal(tab.generationRecovery.id, "interrupted")
+  })
+
+  it("keeps later expansion while loaded collapse and deletion remain authoritative", () => {
+    const saved = session([workspace("/work", 0, { expandedSessionIds: ["loaded", "later", "deleted"] })])
+    const merged = mergeRestorableSessionState(
+      session([workspace("/work", 0, { expandedSessionIds: ["current", "deleted"] })]),
+      restored(saved, [{ source: 0, runtime: "instance:work", unavailable: ["later", "deleted"] }]),
+      {
+        currentTabIds: ["instance:work"],
+        currentTabAuthorities: [{ sessionExpansion: new Set(["loaded"]), deletedSessions: new Set(["deleted"]) }],
+      },
+    )
+    assert.deepEqual(workspaceAt(merged).expandedSessionIds, ["current", "later"])
+  })
+
+  for (const testCase of [
+    { label: "later parent/child selection", current: { activeParentSessionId: "current-parent", activeSessionId: "current-child" },
+      expected: ["current-parent", "current-child"] },
+    { label: "current info selection", current: { activeSessionId: "info" }, expected: [undefined, "info"] },
+    { label: "untouched runtime selection", current: {}, expected: ["missing-parent", "missing-child"] },
+  ]) {
+    it(`handles user selection during restore: ${testCase.label}`, () => {
+      const saved = session([workspace("/work", 0, {
+        activeParentSessionId: "missing-parent", activeSessionId: "missing-child",
+      })])
+      const merged = mergeRestorableSessionState(
+        session([workspace("/work", 0, testCase.current)]),
+        restored(saved, [{ source: 0, runtime: "instance:work", unavailable: ["missing-parent", "missing-child"] }]),
+        { currentTabIds: ["instance:work"] },
+      )
+      const tab = workspaceAt(merged)
+      assert.deepEqual([tab.activeParentSessionId, tab.activeSessionId], testCase.expected)
+    })
+  }
+
+  it("keeps unresolved and partial payloads until a reopened workspace is actually restored", () => {
+    const saved = session([workspace("/failed", 0, { drafts: { missing: "retry", loaded: "discard" } })])
+    let preservation = createRestorableSessionPreservation(saved)
+    assert.equal(mergeRestorableSessionState(empty(), preservation).tabs.length, 1, "transient absence retained")
+    preservation = markPreservedWorkspaceRemoved(preservation, {
+      runtimeTabId: "instance:failed", folder: "/failed", occurrence: 0,
+    })
+    assert.deepEqual(mergeRestorableSessionState(empty(), preservation), empty(), "explicit close tombstones")
+    preservation = markPreservedWorkspaceReopened(preservation, {
+      runtimeTabId: "instance:reopened", folder: "/failed", occurrence: 0,
+    })
+    assert.equal(mergeRestorableSessionState(empty(), preservation).tabs.length, 1, "reopen clears tombstone")
+    assert.equal(preservation.results[0]?.runtimeTabId, "instance:reopened", "reopen binds the new runtime")
+    recordRestoredTab(preservation, 0, "instance:partial", new Set(["missing"]))
+    markPreservedWorkspaceReopened(preservation, {
+      runtimeTabId: "instance:partial", folder: "/failed", occurrence: 0,
+    })
+    const partial = workspaceAt(mergeRestorableSessionState(session([workspace("/failed")]), preservation, {
+      currentTabIds: ["instance:reopened"],
+    }))
+    assert.deepEqual(partial.drafts, { missing: "retry" }, "reopen retains unavailable payload")
+  })
+
+  it("rebinds preserved state when a workspace runtime is reopened", () => {
+    const preservation = restored(session([workspace("/work")]), [{ source: 0, runtime: "instance:reused" }])
+    assert.equal(preservation.results[0]?.runtimeTabId, "instance:reused")
+    markPreservedWorkspaceReopened(preservation, {
+      runtimeTabId: "instance:reused", folder: "/work", occurrence: 0,
+    })
+    assert.equal(preservation.results[0]?.runtimeTabId, "instance:reused")
+  })
+
+  it("hydrates only a genuine unavailable or removed workspace reopen", () => {
+    const preservation = createRestorableSessionPreservation(session([workspace("/work")]))
+    const opened = { runtimeTabId: "instance:new", folder: "/work", occurrence: 0 }
+    assert.equal(getPreservedWorkspaceReopenTarget(preservation, opened), null, "initial restore create owns hydration")
+    recordRestoredTab(preservation, 0, "instance:old")
+    assert.equal(getPreservedWorkspaceReopenTarget(preservation, opened)?.sourceIndex, 0)
+  })
+
+  it("does not seed or settle after an explicit close during hydration", async () => {
+    const preservation = createRestorableSessionPreservation(session([workspace("/work")]))
+    recordRestoredTab(preservation, 0, "instance:hydrating")
+    let resume!: () => void
+    const hydration = new Promise<void>((resolve) => { resume = resolve })
+    const effects: string[] = []
+    const completion = (async () => {
+      await hydration
+      if (!hasRestoredTabBinding(preservation, 0, "instance:hydrating")) return
+      effects.push("seed", "release", "select")
+      settleRestoredTab(preservation, 0, "instance:hydrating", "instance:hydrating", new Set())
+    })()
+
+    markPreservedWorkspaceRemoved(preservation, {
+      runtimeTabId: "instance:hydrating", folder: "/work", occurrence: 0,
+    })
+    markPreservedWorkspaceReopened(preservation, {
+      runtimeTabId: "instance:reopened", folder: "/work", occurrence: 0,
+    })
+    resume()
+    await completion
+
+    assert.deepEqual(effects, [])
+    assert.deepEqual(preservation.results[0], { status: "pending", runtimeTabId: "instance:reopened" })
+  })
+
+  it("invalidates a pending create commit after close even when the workspace reopens", () => {
+    const preservation = createRestorableSessionPreservation(session([workspace("/work")]))
+    const canCommit = createRestoredTabCommitGuard(preservation, 0)
+
+    markPreservedWorkspaceReopened(preservation, {
+      runtimeTabId: "instance:restore-event", folder: "/work", occurrence: 0,
+    })
+    assert.equal(canCommit(), true, "restore creation events do not invalidate their own response")
+
+    markPreservedWorkspaceRemoved(preservation, {
+      runtimeTabId: "instance:restore-event", folder: "/work", occurrence: 0,
+    })
+    markPreservedWorkspaceReopened(preservation, {
+      runtimeTabId: "instance:user-reopened", folder: "/work", occurrence: 0,
+    })
+    assert.equal(canCommit(), false, "a late response cannot overwrite the close authority")
+  })
+
+  it("compare-and-set settlement cannot overwrite removed or rebound authority", () => {
+    const preservation = createRestorableSessionPreservation(session([workspace("/work")]))
+    recordRestoredTab(preservation, 0, "instance:old")
+    markPreservedWorkspaceRemoved(preservation, {
+      runtimeTabId: "instance:old", folder: "/work", occurrence: 0,
+    })
+    assert.equal(settleRestoredTab(preservation, 0, "instance:old", "instance:old", new Set()), false)
+    assert.equal(settleRestoredTab(preservation, 0, "instance:old", null), false)
+    assert.deepEqual(preservation.results[0], { status: "removed" })
+
+    markPreservedWorkspaceReopened(preservation, {
+      runtimeTabId: "instance:new", folder: "/work", occurrence: 0,
+    })
+    recordRestoredTab(preservation, 0, "instance:new")
+    assert.equal(settleRestoredTab(preservation, 0, "instance:old", null), false)
+    assert.deepEqual(preservation.results[0], { status: "pending", runtimeTabId: "instance:new" })
+    assert.equal(settleRestoredTab(preservation, 0, "instance:new", "instance:new", new Set()), true)
+    assert.equal(preservation.results[0]?.status, "restored")
+  })
+
+  it("does not duplicate recovered or authoritatively deleted sidecars", () => {
+    const recovered = session([sidecar("preview"), sidecar("new")])
+    assert.deepEqual(
+      mergeRestorableSessionState(recovered, createRestorableSessionPreservation(session([sidecar("preview")]))),
+      recovered,
+    )
+    const deleted = restored(session([sidecar("deleted")]), [{ source: 0 }])
+    assert.deepEqual(mergeRestorableSessionState(empty(), deleted), empty())
+  })
+
+  for (const testCase of [
+    { label: "restored tabs reordered", current: [workspace("/b"), workspace("/a")], ids: ["instance:b", "instance:a"], active: 0 },
+    { label: "new tab interleaved", current: [workspace("/a"), sidecar("new"), workspace("/b")],
+      ids: ["instance:a", "sidecar:new", "instance:b"], active: 1 },
+  ]) {
+    it(`keeps current layout: ${testCase.label}`, () => {
+      const saved = session([workspace("/a"), workspace("/b")])
+      const preservation = restored(saved, [
+        { source: 0, runtime: "instance:a" }, { source: 1, runtime: "instance:b" },
+      ])
+      const current = session(testCase.current, testCase.active)
+      assert.deepEqual(mergeRestorableSessionState(current, preservation, { currentTabIds: testCase.ids }), current)
+    })
+  }
+
+  it("keeps current active tabs while shifting around unresolved source tabs", () => {
+    const currentTabs = [workspace("/a"), workspace("/b")]
+    const mapped = restored(session(currentTabs), [
+      { source: 0, runtime: "instance:a", unavailable: ["missing"] },
+      { source: 1, runtime: "instance:b" },
+    ])
+    const options = { currentTabIds: ["instance:a", "instance:b"] }
+    assert.equal(mergeRestorableSessionState(session(currentTabs, 0), mapped, options).activeTabIndex, 0)
+    assert.equal(mergeRestorableSessionState(session(currentTabs, 1), mapped, options).activeTabIndex, 1)
+
+    const unresolved = restored(session([sidecar("unresolved"), ...currentTabs]), [
+      { source: 1, runtime: "instance:a" }, { source: 2, runtime: "instance:b" },
+    ])
+    assert.equal(mergeRestorableSessionState(session(currentTabs, 0), unresolved, options).activeTabIndex, 1)
+    assert.equal(mergeRestorableSessionState(session(currentTabs, 1), unresolved, options).activeTabIndex, 2)
+  })
+
+  it("maps the saved active source tab while startup capture has no active tab", () => {
+    const saved = session([workspace("/a"), workspace("/b"), workspace("/c")], 2)
+    const preservation = restored(saved, [
+      { source: 0, runtime: "instance:a", pending: true },
+      { source: 1, runtime: "instance:b", pending: true },
+      { source: 2, runtime: "instance:c", pending: true },
+    ])
+    const merged = mergeRestorableSessionState(session(saved.tabs, -1), preservation, {
+      currentTabIds: ["instance:a", "instance:b", "instance:c"],
+    })
+    assert.equal(merged.activeTabIndex, 2)
+  })
+
+  it("retains saved session IDs during a sub-debounce startup flush unless selection is authoritative", () => {
+    const saved = session([workspace("/work", 0, {
+      activeParentSessionId: "saved-parent", activeSessionId: "saved-child",
+    })])
+    const preservation = restored(saved, [{ source: 0, runtime: "instance:work", pending: true }])
+    const startup = session([workspace("/work")])
+    const beforeDebounce = mergeRestorableSessionState(startup, preservation, {
+      currentTabIds: ["instance:work"], currentTabAuthorities: [{ sessionSelection: false }],
+    })
+    assert.deepEqual(
+      [workspaceAt(beforeDebounce).activeParentSessionId, workspaceAt(beforeDebounce).activeSessionId],
+      ["saved-parent", "saved-child"],
+    )
+    const cleared = mergeRestorableSessionState(startup, preservation, {
+      currentTabIds: ["instance:work"], currentTabAuthorities: [{ sessionSelection: true }],
+    })
+    assert.deepEqual([workspaceAt(cleared).activeParentSessionId, workspaceAt(cleared).activeSessionId], [undefined, undefined])
+  })
+
+  it("inserts an unresolved tab beside its nearest restored source neighbor", () => {
+    const saved = session([workspace("/a"), sidecar("unresolved"), workspace("/b")], 1)
+    const preservation = restored(saved, [
+      { source: 0, runtime: "instance:a" }, { source: 2, runtime: "instance:b" },
+    ])
+    const merged = mergeRestorableSessionState(session([workspace("/a"), workspace("/b")], 1), preservation, {
+      currentTabIds: ["instance:a", "instance:b"],
+    })
+    assert.deepEqual(labels(merged), ["/a:0", "unresolved", "/b:0"])
+    assert.equal(merged.activeTabIndex, 2)
+  })
+
+  it("maps duplicate folders atomically and follows runtime reorder", () => {
+    const saved = session([
+      workspace("/same", 0, { drafts: { first: "source first" } }),
+      workspace("/same", 1, { drafts: { second: "source second" } }),
+      workspace("/same", 2),
+    ])
+    const preservation = restored(saved, [
+      { source: 0, runtime: "instance:first", pending: true },
+      { source: 1, runtime: "instance:second", pending: true },
+      { source: 2, runtime: "instance:last", pending: true },
+    ])
+    assert.deepEqual(preservation.results.map((result) => result.runtimeTabId), [
+      "instance:first", "instance:second", "instance:last",
+    ], "all duplicate bindings are recorded before close events")
+    const reordered = mergeRestorableSessionState(
+      session([workspace("/same", 1), workspace("/same", 0), workspace("/same", 2)]),
+      preservation,
+      { currentTabIds: ["instance:second", "instance:first", "instance:last"] },
+    )
+    assert.equal(workspaceAt(reordered, 0).drafts.second, "source second")
+    assert.equal(workspaceAt(reordered, 1).drafts.first, "source first")
+  })
+
+  it("tombstones duplicate folders independently in either close order", () => {
+    for (const order of [[0, 1], [1, 0]]) {
+      const saved = session([
+        workspace("/same", 0, { drafts: { first: "first" } }),
+        workspace("/same", 1, { drafts: { second: "second" } }),
+      ])
+      const preservation = restored(saved, [
+        { source: 0, runtime: "instance:first", pending: true },
+        { source: 1, runtime: "instance:second", pending: true },
+      ])
+      for (const source of order) markPreservedWorkspaceRemoved(preservation, {
+        runtimeTabId: `instance:${source ? "second" : "first"}`, folder: "/same", occurrence: source,
+      })
+      assert.equal(mergeRestorableSessionState(empty(), preservation).tabs.length, 0, `close order ${order.join(",")}`)
+    }
+  })
+
+  it("retains mapped duplicates during transient absence and only the uncertain remaining source", () => {
+    const saved = session([
+      workspace("/same", 0, { drafts: { first: "first source" } }),
+      workspace("/same", 1, { drafts: { second: "uncertain source" } }),
+    ])
+    const absent = restored(saved, [
+      { source: 0, runtime: "instance:first", pending: true },
+      { source: 1, runtime: "instance:second", pending: true },
+    ])
+    assert.equal(mergeRestorableSessionState(empty(), absent).tabs.length, 2)
+
+    const uncertain = createRestorableSessionPreservation(saved)
+    markPreservedWorkspaceRemoved(uncertain, { runtimeTabId: "unknown:first", folder: "/same", occurrence: 0 })
+    markPreservedWorkspaceRemoved(uncertain, { runtimeTabId: "unknown:second", folder: "/same", occurrence: 0 })
+    const merged = mergeRestorableSessionState(empty(), uncertain)
+    assert.equal(merged.tabs.length, 1)
+    assert.equal(workspaceAt(merged).drafts.second, "uncertain source")
+  })
+
+  it("does not relaunch a closed duplicate after occurrences renumber", () => {
+    const saved = session([
+      workspace("/same", 0), workspace("/same", 1, { drafts: { missing: "preserve" } }),
+    ], 1)
+    const preservation = restored(saved, [
+      { source: 0, runtime: "instance:first" },
+      { source: 1, runtime: "instance:second", unavailable: ["missing"] },
+    ])
+    const merged = mergeRestorableSessionState(
+      session([workspace("/same", 0, { drafts: { current: "captured" } })]),
+      preservation,
+      { currentTabIds: ["instance:second"] },
+    )
+    assert.equal(merged.tabs.length, 1)
+    assert.deepEqual(workspaceAt(merged).drafts, { missing: "preserve", current: "captured" })
+    assert.deepEqual(reconcileWorkspaceTabs(
+      [{ kind: "workspace", folderPath: "/same", occurrence: 0 }],
+      [{ id: "second", folderPath: "/same" }],
+    ).map((match) => match.existingWorkspaceId), ["second"])
+  })
+
+  it("assigns unresolved duplicate a distinct occurrence and reconciliation slot", () => {
+    const saved = session([
+      workspace("/same", 0, { drafts: { failed: "retry" } }),
+      workspace("/same", 1, { drafts: { restored: "saved" } }),
+    ], 1)
+    const merged = mergeRestorableSessionState(
+      session([workspace("/same", 0, { drafts: { current: "captured" } })]),
+      restored(saved, [{ source: 1, runtime: "instance:second" }]),
+      { currentTabIds: ["instance:second"] },
+    )
+    assert.deepEqual(labels(merged), ["/same:1", "/same:0"])
+    assert.equal(workspaceAt(merged, 0).drafts.failed, "retry")
+    const matches = reconcileWorkspaceTabs(
+      merged.tabs.map((tab) => tab.kind === "workspace"
+        ? { kind: "workspace", folderPath: tab.folder, occurrence: tab.occurrence }
+        : { kind: "sidecar" }),
+      [{ id: "second", folderPath: "/same" }],
+    )
+    assert.deepEqual(matches.map((match) => match.existingWorkspaceId), [null, "second"])
+    assert.equal(matches.filter((match) => !match.existingWorkspaceId).length, 1)
+  })
+})
diff --git a/packages/ui/src/stores/app-session-snapshot-merge.ts b/packages/ui/src/stores/app-session-snapshot-merge.ts
new file mode 100644
index 00000000..b7d82b56
--- /dev/null
+++ b/packages/ui/src/stores/app-session-snapshot-merge.ts
@@ -0,0 +1,307 @@
+import type {
+  RestorableSessionState,
+  RestorableTabState,
+  RestorableWorkspaceTabState,
+} from "./client-state-codec"
+import { normalizeWorkspacePath } from "./app-session-reconciliation"
+export interface RestoreTabResult {
+  status: "pending" | "restored" | "removed"
+  runtimeTabId?: string | null
+  unavailableSessionIds?: ReadonlySet<string>
+}
+export interface RestorableSessionPreservation {
+  sourceTabs: RestorableTabState[]
+  activeTabIndex: number
+  results: RestoreTabResult[]
+  removalRevisions: number[]
+}
+export interface RestorableWorkspaceRuntimeAuthority {
+  drafts?: ReadonlySet<string>
+  attachments?: ReadonlySet<string>
+  scrollSnapshots?: ReadonlySet<string>
+  idleMarkers?: ReadonlySet<string>
+  generationRecovery?: ReadonlySet<string>
+  sessionExpansion?: ReadonlySet<string>
+  deletedSessions?: ReadonlySet<string>
+  sessionSelection?: boolean
+}
+interface TabIdentity {
+  key: string
+  occurrence: number
+  value: string
+}
+function mapTabIdentities(tabs: readonly RestorableTabState[]): TabIdentity[] {
+  const nextOccurrences = new Map<string, number>()
+  return tabs.map((tab) => {
+    const key = tab.kind === "workspace"
+      ? `workspace:${normalizeWorkspacePath(tab.folder)}`
+      : `sidecar:${tab.sidecarId}`
+    const inferred = nextOccurrences.get(key) ?? 0
+    const occurrence = tab.kind === "workspace" ? tab.occurrence ?? inferred : inferred
+    nextOccurrences.set(key, Math.max(inferred, occurrence) + 1)
+    return { key, occurrence, value: `${key}:${occurrence}` }
+  })
+}
+export function createRestorableSessionPreservation(
+  snapshot: RestorableSessionState,
+): RestorableSessionPreservation {
+  return {
+    sourceTabs: [...snapshot.tabs],
+    activeTabIndex: snapshot.activeTabIndex,
+    results: snapshot.tabs.map(() => ({ status: "pending" })),
+    removalRevisions: snapshot.tabs.map(() => 0),
+  }
+}
+export function createRestoredTabCommitGuard(
+  preservation: RestorableSessionPreservation,
+  sourceIndex: number,
+): () => boolean {
+  const removalRevision = preservation.removalRevisions[sourceIndex]
+  return () => preservation.removalRevisions[sourceIndex] === removalRevision
+}
+export function recordRestoredTab(
+  preservation: RestorableSessionPreservation,
+  sourceIndex: number,
+  runtimeTabId: string | null,
+  unavailableSessionIds?: ReadonlySet<string>,
+): void {
+  if (!preservation.sourceTabs[sourceIndex]) return
+  preservation.results[sourceIndex] = unavailableSessionIds
+    ? { status: "restored", runtimeTabId, unavailableSessionIds }
+    : { status: "pending", ...(runtimeTabId ? { runtimeTabId } : {}) }
+}
+export function hasRestoredTabBinding(
+  preservation: RestorableSessionPreservation,
+  sourceIndex: number,
+  expectedRuntimeTabId: string,
+): boolean {
+  const result = preservation.results[sourceIndex]
+  return Boolean(result?.status === "pending" && result.runtimeTabId === expectedRuntimeTabId)
+}
+export function settleRestoredTab(
+  preservation: RestorableSessionPreservation,
+  sourceIndex: number,
+  expectedRuntimeTabId: string,
+  runtimeTabId: string | null,
+  unavailableSessionIds?: ReadonlySet<string>,
+): boolean {
+  if (!hasRestoredTabBinding(preservation, sourceIndex, expectedRuntimeTabId)) return false
+  recordRestoredTab(preservation, sourceIndex, runtimeTabId, unavailableSessionIds)
+  return true
+}
+function findWorkspaceSourceIndex(
+  preservation: RestorableSessionPreservation,
+  workspace: { runtimeTabId: string; folder: string; occurrence: number },
+): number | undefined {
+  const runtimeIndex = preservation.results.findIndex((result) => result.runtimeTabId === workspace.runtimeTabId)
+  if (runtimeIndex >= 0) return runtimeIndex
+  const identity = `workspace:${normalizeWorkspacePath(workspace.folder)}:${workspace.occurrence}`
+  const index = mapTabIdentities(preservation.sourceTabs).findIndex((candidate) => candidate.value === identity)
+  return index >= 0 ? index : undefined
+}
+export function getPreservedWorkspaceState(
+  preservation: RestorableSessionPreservation,
+  workspace: { runtimeTabId: string; folder: string; occurrence: number },
+): RestorableWorkspaceTabState | null {
+  const index = preservation.results.findIndex((result) => result.runtimeTabId === workspace.runtimeTabId)
+  const source = preservation.sourceTabs[index]
+  return source?.kind === "workspace" ? source : null
+}
+export function getPreservedWorkspaceReopenTarget(
+  preservation: RestorableSessionPreservation,
+  workspace: { runtimeTabId: string; folder: string; occurrence: number },
+): { sourceIndex: number; snapshot: RestorableWorkspaceTabState } | null {
+  const sourceIndex = findWorkspaceSourceIndex(preservation, workspace)
+  if (sourceIndex === undefined) return null
+  const result = preservation.results[sourceIndex]
+  const source = preservation.sourceTabs[sourceIndex]
+  if ((!result?.runtimeTabId && result?.status !== "removed") || source?.kind !== "workspace") return null
+  return { sourceIndex, snapshot: source }
+}
+export function markPreservedWorkspaceRemoved(
+  preservation: RestorableSessionPreservation,
+  workspace: { runtimeTabId: string; folder: string; occurrence: number },
+): RestorableSessionPreservation {
+  const index = findWorkspaceSourceIndex(preservation, workspace)
+  if (index !== undefined && preservation.results[index]?.status === "pending") {
+    preservation.results[index] = { status: "removed" }
+    preservation.removalRevisions[index] = (preservation.removalRevisions[index] ?? 0) + 1
+  }
+  return preservation
+}
+export function markPreservedWorkspaceReopened(
+  preservation: RestorableSessionPreservation,
+  workspace: { runtimeTabId: string; folder: string; occurrence: number },
+): RestorableSessionPreservation {
+  const index = findWorkspaceSourceIndex(preservation, workspace)
+  if (index === undefined) return preservation
+  const result = preservation.results[index]
+  preservation.results[index] = result?.status === "removed"
+    ? { status: "pending", runtimeTabId: workspace.runtimeTabId }
+    : { ...result, status: "pending", runtimeTabId: workspace.runtimeTabId }
+  return preservation
+}
+function getPreservedTab(source: RestorableTabState, result: RestoreTabResult): RestorableTabState | null {
+  const unavailable = result.unavailableSessionIds
+  if (result.status === "pending" && !unavailable) return source
+  if ((result.status !== "restored" && result.status !== "pending") || source.kind !== "workspace" || !unavailable?.size) return null
+  const keep = <T>(record: Record<string, T>) => Object.fromEntries(
+    Object.entries(record).filter(([id]) => unavailable.has(id)),
+  )
+  const tab: RestorableWorkspaceTabState = {
+    kind: "workspace",
+    folder: source.folder,
+    drafts: keep(source.drafts),
+    attachments: keep(source.attachments),
+    scrollSnapshots: keep(source.scrollSnapshots),
+    unseenIdleSince: keep(source.unseenIdleSince),
+    generationRecovery: keep(source.generationRecovery),
+    expandedSessionIds: (source.expandedSessionIds ?? []).filter((id) => unavailable.has(id)),
+  }
+  if (source.occurrence !== undefined) tab.occurrence = source.occurrence
+  if (source.activeParentSessionId && unavailable.has(source.activeParentSessionId)) {
+    tab.activeParentSessionId = source.activeParentSessionId
+  }
+  if (source.activeSessionId && unavailable.has(source.activeSessionId)) tab.activeSessionId = source.activeSessionId
+  return tab
+}
+function mergeWorkspaceState(
+  current: RestorableWorkspaceTabState,
+  preserved: RestorableWorkspaceTabState,
+  authority: RestorableWorkspaceRuntimeAuthority = {},
+): RestorableWorkspaceTabState {
+  const mergeRecords = <T>(currentRecord: Record<string, T>, fallback: Record<string, T>, owned?: ReadonlySet<string>) => {
+    const preservedRecord = { ...fallback }
+    for (const id of [...(owned ?? []), ...(authority.deletedSessions ?? [])]) delete preservedRecord[id]
+    return { ...preservedRecord, ...currentRecord }
+  }
+  const result: RestorableWorkspaceTabState = {
+    ...current,
+    drafts: mergeRecords(current.drafts, preserved.drafts, authority.drafts),
+    attachments: mergeRecords(current.attachments, preserved.attachments, authority.attachments),
+    scrollSnapshots: mergeRecords(current.scrollSnapshots, preserved.scrollSnapshots, authority.scrollSnapshots),
+    unseenIdleSince: mergeRecords(current.unseenIdleSince, preserved.unseenIdleSince, authority.idleMarkers),
+    generationRecovery: mergeRecords(current.generationRecovery, preserved.generationRecovery, authority.generationRecovery),
+    expandedSessionIds: [
+      ...(current.expandedSessionIds ?? []).filter((id) => !authority.deletedSessions?.has(id)),
+      ...(preserved.expandedSessionIds ?? []).filter((id) =>
+        !authority.sessionExpansion?.has(id) && !authority.deletedSessions?.has(id)),
+    ].filter((id, index, values) => values.indexOf(id) === index),
+  }
+  const restoreSelection = !authority.sessionSelection && !current.activeParentSessionId && !current.activeSessionId
+  if (restoreSelection && preserved.activeParentSessionId && !authority.deletedSessions?.has(preserved.activeParentSessionId)) {
+    result.activeParentSessionId = preserved.activeParentSessionId
+  }
+  if (restoreSelection && preserved.activeSessionId && !authority.deletedSessions?.has(preserved.activeSessionId)) {
+    result.activeSessionId = preserved.activeSessionId
+  }
+  return result
+}
+function nearestInsertionSlot(sourceIndex: number, matches: readonly (number | undefined)[], fallback: number): number {
+  for (let distance = 1; distance < matches.length; distance += 1) {
+    const before = sourceIndex - distance
+    const after = sourceIndex + distance
+    if (before >= 0 && matches[before] !== undefined) return matches[before]! + 1
+    if (after < matches.length && matches[after] !== undefined) return matches[after]!
+  }
+  return fallback
+}
+export function mergeRestorableSessionState(
+  current: RestorableSessionState,
+  preservation: RestorableSessionPreservation | null,
+  options: {
+    currentTabIds?: readonly string[]
+    currentTabAuthorities?: readonly (RestorableWorkspaceRuntimeAuthority | undefined)[]
+  } = {},
+): RestorableSessionState {
+  if (!preservation) return current
+  const currentIdentities = mapTabIdentities(current.tabs)
+  const sourceIdentities = mapTabIdentities(preservation.sourceTabs)
+  const indexesByIdentity = new Map<string, number[]>()
+  currentIdentities.forEach(({ value }, index) => {
+    indexesByIdentity.set(value, [...(indexesByIdentity.get(value) ?? []), index])
+  })
+  const indexesByRuntimeId = new Map((options.currentTabIds ?? []).map((id, index) => [id, index]))
+  const matches: Array<number | undefined> = preservation.sourceTabs.map(() => undefined)
+  const claimed = new Set<number>()
+  const claim = (sourceIndex: number, currentIndex: number | undefined) => {
+    if (currentIndex === undefined || !current.tabs[currentIndex] || claimed.has(currentIndex)) return
+    matches[sourceIndex] = currentIndex
+    claimed.add(currentIndex)
+  }
+  preservation.results.forEach((result, index) => {
+    if (result.runtimeTabId) claim(index, indexesByRuntimeId.get(result.runtimeTabId))
+  })
+  preservation.results.forEach((result, index) => {
+    if (matches[index] !== undefined || (result.status !== "pending" && options.currentTabIds)) return
+    claim(index, indexesByIdentity.get(sourceIdentities[index]!.value)?.find((candidate) => !claimed.has(candidate)))
+  })
+  const currentTabs = [...current.tabs]
+  preservation.sourceTabs.forEach((source, index) => {
+    const currentIndex = matches[index]
+    const target = currentIndex === undefined ? undefined : currentTabs[currentIndex]
+    const fallback = getPreservedTab(source, preservation.results[index]!)
+    if (target?.kind === "workspace" && fallback?.kind === "workspace") {
+      currentTabs[currentIndex!] = mergeWorkspaceState(target, fallback, options.currentTabAuthorities?.[currentIndex!])
+    }
+  })
+  const insertions = new Map<number, Array<{ sourceIndex: number; tab: RestorableTabState }>>()
+  const usedOccurrences = new Map<string, Set<number>>()
+  currentIdentities.forEach(({ key, occurrence }) => {
+    const used = usedOccurrences.get(key) ?? new Set<number>()
+    used.add(occurrence)
+    usedOccurrences.set(key, used)
+  })
+  preservation.sourceTabs.forEach((source, index) => {
+    if (matches[index] !== undefined || preservation.results[index]?.status !== "pending") return
+    const slot = nearestInsertionSlot(index, matches, currentTabs.length)
+    let tab = source
+    if (source.kind === "workspace") {
+      const { key, occurrence: sourceOccurrence } = sourceIdentities[index]!
+      const used = usedOccurrences.get(key) ?? new Set<number>()
+      let occurrence = sourceOccurrence
+      while (used.has(occurrence)) occurrence += 1
+      used.add(occurrence)
+      usedOccurrences.set(key, used)
+      tab = { ...source, occurrence }
+    }
+    insertions.set(slot, [...(insertions.get(slot) ?? []), { sourceIndex: index, tab }])
+  })
+  const outputIndexes = new Map<number, number>()
+  const sourceOutputIndexes = new Map<number, number>()
+  const tabs: RestorableTabState[] = []
+  for (let slot = 0; slot <= currentTabs.length; slot += 1) {
+    for (const insertion of insertions.get(slot) ?? []) {
+      sourceOutputIndexes.set(insertion.sourceIndex, tabs.length)
+      tabs.push(insertion.tab)
+    }
+    if (!currentTabs[slot]) continue
+    outputIndexes.set(slot, tabs.length)
+    const sourceIndex = matches.findIndex((currentIndex) => currentIndex === slot)
+    if (sourceIndex >= 0) sourceOutputIndexes.set(sourceIndex, tabs.length)
+    tabs.push(currentTabs[slot]!)
+  }
+  const activeTabIndex = outputIndexes.get(current.activeTabIndex)
+    ?? sourceOutputIndexes.get(preservation.activeTabIndex)
+    ?? (tabs.length ? 0 : -1)
+  return {
+    tabs,
+    activeTabIndex,
+    ...(current.homeActive === true ? { homeActive: true } : {}),
+  }
+}
+export function markPreservedWorkspaceUnavailable(
+  preservation: RestorableSessionPreservation,
+  workspace: { runtimeTabId: string; folder: string; occurrence: number },
+  current?: RestorableWorkspaceTabState,
+  authority?: RestorableWorkspaceRuntimeAuthority,
+): RestorableSessionPreservation {
+  const index = findWorkspaceSourceIndex(preservation, workspace)
+  if (index === undefined) return preservation
+  const source = preservation.sourceTabs[index]
+  if (current) preservation.sourceTabs[index] = source?.kind === "workspace"
+    ? mergeWorkspaceState(current, source, authority)
+    : current
+  preservation.results[index] = { status: "pending", runtimeTabId: workspace.runtimeTabId }
+  return preservation
+}
diff --git a/packages/ui/src/stores/app-session-workspace-hydration.ts b/packages/ui/src/stores/app-session-workspace-hydration.ts
new file mode 100644
index 00000000..9955eff0
--- /dev/null
+++ b/packages/ui/src/stores/app-session-workspace-hydration.ts
@@ -0,0 +1,48 @@
+import type { RestorableWorkspaceTabState } from "./client-state-codec"
+import { getUnavailableRestoredSessionIds, resolveRestoredSessionSelection } from "./app-session-reconciliation"
+import { getAbortReason } from "./app-session-restore-timeout"
+import { hydrateWorkspacePromptState } from "./app-session-prompt-hydration"
+import { messageStoreBus, type MessageScrollSnapshotSeed } from "./message-v2/bus"
+import { getSessionAncestorIdsFromMap } from "./session-tree"
+import {
+  getSessions, hasAuthoritativeSessionSelection, hydrateActiveSessionSelection,
+  hydrateRestoredSessionChain, hydrateSessionExpansion, hydrateSessionGenerationRecovery, hydrateSessionIdleMarkers,
+} from "./sessions"
+
+const MESSAGE_SCROLL_SCOPE = "message-stream"
+export const NO_SESSION_DRAFT_SESSION_ID = "__no_session_draft__"
+
+export async function hydrateRestoredWorkspaceState(
+  instanceId: string,
+  snapshot: RestorableWorkspaceTabState,
+  signal: AbortSignal,
+  isCurrentBinding: () => boolean,
+): Promise<Set<string> | null> {
+  await hydrateRestoredSessionChain(instanceId, [snapshot.activeParentSessionId, snapshot.activeSessionId], signal)
+  if (signal.aborted) throw getAbortReason(signal)
+  if (!isCurrentBinding()) return null
+  const sessions = getSessions(instanceId)
+  const validIds = new Set(sessions.map(({ id }) => id))
+  const selection = resolveRestoredSessionSelection(sessions, snapshot.activeParentSessionId, snapshot.activeSessionId)
+  const unavailable = getUnavailableRestoredSessionIds(sessions, {
+    activeParentSessionId: snapshot.activeParentSessionId, activeSessionId: snapshot.activeSessionId,
+    draftSessionIds: Object.keys(snapshot.drafts), attachmentSessionIds: Object.keys(snapshot.attachments),
+    scrollSessionIds: Object.keys(snapshot.scrollSnapshots), idleMarkerSessionIds: Object.keys(snapshot.unseenIdleSince),
+    generationRecoverySessionIds: Object.keys(snapshot.generationRecovery),
+    expandedSessionIds: snapshot.expandedSessionIds ?? [],
+  }, [NO_SESSION_DRAFT_SESSION_ID])
+  hydrateWorkspacePromptState(instanceId, snapshot, validIds, NO_SESSION_DRAFT_SESSION_ID)
+  hydrateSessionIdleMarkers(instanceId, snapshot.unseenIdleSince)
+  hydrateSessionGenerationRecovery(instanceId, snapshot.generationRecovery)
+  const expandedSessionIds = snapshot.expandedSessionIds ?? (!hasAuthoritativeSessionSelection(instanceId) && selection?.activeSessionId
+    ? getSessionAncestorIdsFromMap(new Map(sessions.map((session) => [session.id, session])), selection.activeSessionId)
+    : [])
+  hydrateSessionExpansion(instanceId, expandedSessionIds)
+  const scrollSeeds: MessageScrollSnapshotSeed[] = Object.entries(snapshot.scrollSnapshots)
+    .map(([sessionId, scrollSnapshot]) => ({ sessionId, scope: MESSAGE_SCROLL_SCOPE, snapshot: scrollSnapshot }))
+  messageStoreBus.seedScrollSnapshots(instanceId, scrollSeeds)
+  if (!hasAuthoritativeSessionSelection(instanceId)) {
+    hydrateActiveSessionSelection(instanceId, selection?.parentSessionId ?? null, selection?.activeSessionId ?? null)
+  }
+  return unavailable
+}
diff --git a/packages/ui/src/stores/app-tabs.ts b/packages/ui/src/stores/app-tabs.ts
index 3b76627b..e1cfadf2 100644
--- a/packages/ui/src/stores/app-tabs.ts
+++ b/packages/ui/src/stores/app-tabs.ts
@@ -1,7 +1,8 @@
 import { createMemo, createSignal } from "solid-js"
 import type { Instance } from "../types/instance"
-import { activeInstanceId, instances, setActiveInstanceId } from "./instances"
+import { activeInstanceId, claimRestoreCreatedInstanceForUser, instances, setActiveInstanceId } from "./instances"
 import { activeSidecarToken, setActiveSidecarToken, sidecarTabs, type SideCarTabRecord } from "./sidecars"
+import { appSessionRestoreGateActive } from "./app-session-restore-gate"
 
 export interface InstanceAppTab {
   id: string
@@ -48,6 +49,8 @@ function getPreferredTabId(): string | null {
 
 const [activeAppTabId, setActiveAppTabId] = createSignal<string | null>(null)
 const [tabOrder, setTabOrder] = createSignal<string[]>([])
+const [appTabSelectionRevision, setAppTabSelectionRevision] = createSignal(0)
+const [appTabOrderRevision, setAppTabOrderRevision] = createSignal(0)
 
 function rememberTabOrder(tabId: string) {
   setTabOrder((prev) => (prev.includes(tabId) ? prev : [...prev, tabId]))
@@ -81,7 +84,8 @@ function getAppTabById(tabId: string | null): AppTabRecord | null {
   return appTabs().find((tab) => tab.id === tabId) ?? null
 }
 
-function selectAppTab(tabId: string | null) {
+function selectAppTab(tabId: string | null, options?: { source?: "restore" }) {
+  if (options?.source !== "restore") setAppTabSelectionRevision((revision) => revision + 1)
   if (!tabId) {
     setActiveAppTabId(null)
     setActiveSidecarToken(null)
@@ -95,6 +99,7 @@ function selectAppTab(tabId: string | null) {
   setActiveAppTabId(tab.id)
 
   if (tab.kind === "instance") {
+    if (options?.source !== "restore") claimRestoreCreatedInstanceForUser(tab.instance.id)
     setActiveSidecarToken(null)
     setActiveInstanceId(tab.instance.id)
     return
@@ -125,6 +130,31 @@ function moveAppTab(tabId: string, targetTabId: string, placement: "before" | "a
 
   reorderedIds.splice(placement === "after" ? targetIndex + 1 : targetIndex, 0, tabId)
   setTabOrder(reorderedIds)
+  setAppTabOrderRevision((revision) => revision + 1)
+}
+
+function markAppTabUserInteraction() {
+  setAppTabSelectionRevision((revision) => revision + 1)
+  setAppTabOrderRevision((revision) => revision + 1)
+}
+
+function setAppTabOrder(tabIds: string[]) {
+  const availableIds = appTabs().map((tab) => tab.id)
+  const available = new Set(availableIds)
+  const seen = new Set<string>()
+  const orderedIds: string[] = []
+
+  for (const tabId of tabIds) {
+    if (!available.has(tabId) || seen.has(tabId)) continue
+    seen.add(tabId)
+    orderedIds.push(tabId)
+  }
+  for (const tabId of availableIds) {
+    if (seen.has(tabId)) continue
+    orderedIds.push(tabId)
+  }
+
+  setTabOrder(orderedIds)
 }
 
 function selectNextAppTab() {
@@ -153,6 +183,7 @@ function selectAppTabByIndex(index: number) {
 }
 
 function ensureActiveAppTab(preferredTabId?: string | null) {
+  if (appSessionRestoreGateActive()) return
   const tabs = appTabs()
   const current = activeAppTabId()
 
@@ -171,6 +202,8 @@ function ensureActiveAppTab(preferredTabId?: string | null) {
 
 export {
   activeAppTabId,
+  appTabOrderRevision,
+  appTabSelectionRevision,
   activeAppTab,
   appTabs,
   ensureActiveAppTab,
@@ -178,7 +211,9 @@ export {
   getAppTabById,
   getInstanceAppTabId,
   getSidecarAppTabId,
+  markAppTabUserInteraction,
   moveAppTab,
+  setAppTabOrder,
   selectAppTab,
   selectAppTabByIndex,
   selectInstanceTab,
diff --git a/packages/ui/src/stores/attachments.test.ts b/packages/ui/src/stores/attachments.test.ts
new file mode 100644
index 00000000..38134aae
--- /dev/null
+++ b/packages/ui/src/stores/attachments.test.ts
@@ -0,0 +1,45 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { createTextAttachment } from "../types/attachment.ts"
+import {
+  clearInstanceAttachmentValues,
+  clearInstanceAttachments,
+  getAuthoritativeAttachmentSessionIdsForInstance,
+  getAttachments,
+  getSessionAttachmentsForInstance,
+  hydrateSessionAttachments,
+  removeAttachment,
+} from "./attachments.ts"
+
+describe("attachment hydration", () => {
+  it("hydrates and captures attachments by instance and session", () => {
+    const attachment = createTextAttachment("restored text", "pasted #1 (4 lines)", "paste-1.txt")
+    hydrateSessionAttachments("restore-instance", "session-1", [attachment])
+
+    assert.deepEqual(getAttachments("restore-instance", "session-1"), [attachment])
+    assert.deepEqual(getSessionAttachmentsForInstance("restore-instance"), { "session-1": [attachment] })
+
+    clearInstanceAttachments("restore-instance")
+    assert.deepEqual(getSessionAttachmentsForInstance("restore-instance"), {})
+  })
+
+  it("records an authoritative tombstone when the last attachment is removed", () => {
+    const instanceId = "removed-last-attachment-instance"
+    const sessionId = "session-1"
+    const attachment = createTextAttachment("restored text", "pasted #1 (4 lines)", "paste-1.txt")
+    hydrateSessionAttachments(instanceId, sessionId, [attachment])
+
+    assert.equal(getAuthoritativeAttachmentSessionIdsForInstance(instanceId).has(sessionId), false)
+    removeAttachment(instanceId, sessionId, attachment.id)
+
+    assert.deepEqual(getSessionAttachmentsForInstance(instanceId), {})
+    assert.equal(getAuthoritativeAttachmentSessionIdsForInstance(instanceId).has(sessionId), true)
+
+    clearInstanceAttachmentValues(instanceId)
+    assert.equal(getAuthoritativeAttachmentSessionIdsForInstance(instanceId).has(sessionId), true)
+
+    clearInstanceAttachments(instanceId)
+    assert.equal(getAuthoritativeAttachmentSessionIdsForInstance(instanceId).has(sessionId), false)
+  })
+})
diff --git a/packages/ui/src/stores/attachments.ts b/packages/ui/src/stores/attachments.ts
index 5e2ad10e..41d695d2 100644
--- a/packages/ui/src/stores/attachments.ts
+++ b/packages/ui/src/stores/attachments.ts
@@ -1,47 +1,109 @@
 import { createSignal } from "solid-js"
 import type { Attachment } from "../types/attachment"
 
-const [attachments, setAttachments] = createSignal<Map<string, Attachment[]>>(new Map())
+interface SessionAttachmentState {
+  values: Attachment[]
+  authoritative: boolean
+}
 
-function getSessionKey(instanceId: string, sessionId: string): string {
-  return `${instanceId}:${sessionId}`
+const [attachments, setAttachments] = createSignal<Map<string, SessionAttachmentState>>(new Map())
+
+const getSessionKey = (instanceId: string, sessionId: string) => `${instanceId}:${sessionId}`
+
+function setSession(instanceId: string, sessionId: string, state?: SessionAttachmentState) {
+  const key = getSessionKey(instanceId, sessionId)
+  setAttachments((previous) => {
+    const next = new Map(previous)
+    if (state) next.set(key, state)
+    else next.delete(key)
+    return next
+  })
 }
 
 function getAttachments(instanceId: string, sessionId: string): Attachment[] {
-  const key = getSessionKey(instanceId, sessionId)
-  return attachments().get(key) || []
+  return attachments().get(getSessionKey(instanceId, sessionId))?.values ?? []
+}
+
+function getInstanceEntries(instanceId: string) {
+  const prefix = `${instanceId}:`
+  return [...attachments()].filter(([key]) => key.startsWith(prefix))
+    .map(([key, state]) => [key.slice(prefix.length), state] as const)
+}
+
+function getSessionAttachmentsForInstance(instanceId: string): Record<string, Attachment[]> {
+  if (!instanceId) return {}
+  return Object.fromEntries(
+    getInstanceEntries(instanceId)
+      .filter(([, state]) => state.values.length > 0)
+      .map(([sessionId, state]) => [sessionId, [...state.values]]),
+  )
+}
+
+function getAuthoritativeAttachmentSessionIdsForInstance(instanceId: string): ReadonlySet<string> {
+  if (!instanceId) return new Set()
+  return new Set(
+    getInstanceEntries(instanceId)
+      .filter(([, state]) => state.authoritative)
+      .map(([sessionId]) => sessionId),
+  )
 }
 
 function addAttachment(instanceId: string, sessionId: string, attachment: Attachment) {
-  const key = getSessionKey(instanceId, sessionId)
-  setAttachments((prev) => {
-    const next = new Map(prev)
-    const existing = next.get(key) || []
-    next.set(key, [...existing, attachment])
-    return next
+  setSession(instanceId, sessionId, {
+    values: [...getAttachments(instanceId, sessionId), attachment],
+    authoritative: true,
   })
 }
 
 function removeAttachment(instanceId: string, sessionId: string, attachmentId: string) {
-  const key = getSessionKey(instanceId, sessionId)
-  setAttachments((prev) => {
-    const next = new Map(prev)
-    const existing = next.get(key) || []
-    next.set(
-      key,
-      existing.filter((a) => a.id !== attachmentId),
-    )
-    return next
+  setSession(instanceId, sessionId, {
+    values: getAttachments(instanceId, sessionId).filter((attachment) => attachment.id !== attachmentId),
+    authoritative: true,
   })
 }
 
 function clearAttachments(instanceId: string, sessionId: string) {
-  const key = getSessionKey(instanceId, sessionId)
-  setAttachments((prev) => {
-    const next = new Map(prev)
-    next.delete(key)
+  setSession(instanceId, sessionId, { values: [], authoritative: true })
+}
+
+function deleteSessionAttachments(instanceId: string, sessionId: string) {
+  setSession(instanceId, sessionId)
+}
+
+function hydrateSessionAttachments(instanceId: string, sessionId: string, values: Attachment[]) {
+  setSession(instanceId, sessionId, {
+    values: [...values],
+    authoritative: attachments().get(getSessionKey(instanceId, sessionId))?.authoritative ?? false,
+  })
+}
+
+function clearInstanceAttachments(instanceId: string, valuesOnly = false) {
+  if (!instanceId) return
+  const prefix = `${instanceId}:`
+  setAttachments((previous) => {
+    const next = new Map(previous)
+    for (const [key, state] of next) {
+      if (!key.startsWith(prefix)) continue
+      if (valuesOnly && state.authoritative) next.set(key, { ...state, values: [] })
+      else next.delete(key)
+    }
     return next
   })
 }
 
-export { getAttachments, addAttachment, removeAttachment, clearAttachments }
+function clearInstanceAttachmentValues(instanceId: string) {
+  clearInstanceAttachments(instanceId, true)
+}
+
+export {
+  getAttachments,
+  getSessionAttachmentsForInstance,
+  getAuthoritativeAttachmentSessionIdsForInstance,
+  addAttachment,
+  removeAttachment,
+  clearAttachments,
+  deleteSessionAttachments,
+  hydrateSessionAttachments,
+  clearInstanceAttachmentValues,
+  clearInstanceAttachments,
+}
diff --git a/packages/ui/src/stores/client-state-attachments-codec.ts b/packages/ui/src/stores/client-state-attachments-codec.ts
new file mode 100644
index 00000000..1253ddda
--- /dev/null
+++ b/packages/ui/src/stores/client-state-attachments-codec.ts
@@ -0,0 +1,228 @@
+import type { Attachment, AttachmentSource } from "../types/attachment"
+import { removeAttachmentPromptTokens } from "../lib/attachment-mentions"
+
+export type RestorableAttachmentSource =
+  | { type: "file"; path: string; mime: string; data?: string }
+  | { type: "text"; value: string }
+  | { type: "agent"; name: string }
+  | { type: "symbol"; path: string; name: string; kind: number; range: { start: Position; end: Position } }
+
+interface Position {
+  line: number
+  char: number
+}
+
+export interface RestorableAttachment {
+  id: string
+  type: Attachment["type"]
+  display: string
+  url: string
+  filename: string
+  mediaType: string
+  source: RestorableAttachmentSource
+}
+export interface AttachmentCodecBudget {
+  attachmentsRemaining: number
+  metadataCharactersRemaining: number
+  fileDataCharactersRemaining: number
+}
+
+const MAX_SESSIONS = 24
+const MAX_PER_SESSION = 8
+const MAX_ATTACHMENTS = 64
+const MAX_METADATA = 24 * 1024
+const MAX_FILE_BYTES = 64 * 1024
+const MAX_FILE_CHARACTERS = 96 * 1024
+const MAX_ID = 512
+const MAX_DISPLAY = 1024
+const MAX_PATH = 4096
+const MAX_MIME = 256
+const MAX_TEXT = 24 * 1024
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+const isSafeKey = (value: string) =>
+  value !== "__proto__" && value !== "constructor" && value !== "prototype"
+
+function takeString(value: unknown, max: number, budget: AttachmentCodecBudget, allowEmpty = false) {
+  if (
+    typeof value !== "string" ||
+    value.length > max ||
+    value.length > budget.metadataCharactersRemaining
+  ) return
+  if (!allowEmpty && value.trim().length === 0) return
+  budget.metadataCharactersRemaining -= value.length
+  return value
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = ""
+  for (let index = 0; index < bytes.length; index += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000))
+  }
+  return btoa(binary)
+}
+
+const base64ToBytes = (value: string) => Uint8Array.from(atob(value), (character) => character.charCodeAt(0))
+
+function validBase64(value: unknown): value is string {
+  if (typeof value !== "string" || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) return false
+  try {
+    base64ToBytes(value)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const dataUrlPayload = (value: unknown): string | undefined => typeof value === "string"
+  ? value.match(/^data:[^;,]+;base64,([A-Za-z0-9+/]*={0,2})$/)?.[1]
+  : undefined
+
+function takeFileData(value: unknown, url: unknown, budget: AttachmentCodecBudget): string | undefined {
+  const raw = dataUrlPayload(url) ?? value
+  if (raw instanceof Uint8Array && raw.byteLength > MAX_FILE_BYTES) return
+  const data = raw instanceof Uint8Array ? bytesToBase64(raw) : raw
+  if (
+    !validBase64(data) ||
+    base64ToBytes(data).byteLength > MAX_FILE_BYTES ||
+    data.length > MAX_FILE_CHARACTERS ||
+    data.length > budget.fileDataCharactersRemaining
+  ) return
+  budget.fileDataCharactersRemaining -= data.length
+  return data
+}
+
+function takePosition(value: unknown): Position | undefined {
+  if (!isRecord(value) || !Number.isSafeInteger(value.line) || Number(value.line) < 0) return
+  if (!Number.isSafeInteger(value.char) || Number(value.char) < 0) return
+  return { line: Number(value.line), char: Number(value.char) }
+}
+
+function normalizeSource(
+  value: unknown,
+  url: unknown,
+  budget: AttachmentCodecBudget,
+): RestorableAttachmentSource | undefined {
+  if (!isRecord(value)) return
+  if (value.type === "text") {
+    const text = takeString(value.value, MAX_TEXT, budget, true)
+    return text === undefined ? undefined : { type: "text", value: text }
+  }
+  if (value.type === "agent") {
+    const name = takeString(value.name, MAX_DISPLAY, budget)
+    return name === undefined ? undefined : { type: "agent", name }
+  }
+
+  const path = takeString(value.path, MAX_PATH, budget)
+  if (value.type === "file") {
+    const mime = takeString(value.mime, MAX_MIME, budget)
+    if (path === undefined || mime === undefined) return
+    const rawData = dataUrlPayload(url) ?? value.data
+    const data = takeFileData(value.data, url, budget)
+    const pathBacked = typeof url === "string" && url.length > 0 && !url.startsWith("data:")
+    const validPathData = rawData instanceof Uint8Array || validBase64(rawData)
+    if (rawData !== undefined && data === undefined && (!pathBacked || !validPathData)) return
+    return data === undefined ? { type: "file", path, mime } : { type: "file", path, mime, data }
+  }
+  if (value.type !== "symbol" || !isRecord(value.range)) return
+  const name = takeString(value.name, MAX_DISPLAY, budget)
+  const start = takePosition(value.range.start)
+  const end = takePosition(value.range.end)
+  if (path === undefined || name === undefined || !Number.isSafeInteger(value.kind) || !start || !end) return
+  return { type: "symbol", path, name, kind: Number(value.kind), range: { start, end } }
+}
+
+function normalizeAttachment(value: unknown, budget: AttachmentCodecBudget): RestorableAttachment | undefined {
+  if (!isRecord(value) || budget.attachmentsRemaining <= 0) return
+  if (!["file", "text", "symbol", "agent"].includes(String(value.type))) return
+
+  const next = { ...budget }
+  const id = takeString(value.id, MAX_ID, next)
+  const display = takeString(value.display, MAX_DISPLAY, next)
+  const filename = takeString(value.filename, MAX_PATH, next)
+  const mediaType = takeString(value.mediaType, MAX_MIME, next)
+  const source = normalizeSource(value.source, value.url, next)
+  const rawUrl = typeof value.url === "string" && !value.url.startsWith("data:") ? value.url : ""
+  const url = takeString(rawUrl, MAX_PATH, next, true)
+  if (
+    !id || !display || !filename || !mediaType || !source ||
+    source.type !== value.type || url === undefined
+  ) return
+
+  next.attachmentsRemaining -= 1
+  Object.assign(budget, next)
+  return { id, type: value.type as Attachment["type"], display, url, filename, mediaType, source }
+}
+
+export function createAttachmentCodecBudget(): AttachmentCodecBudget {
+  return {
+    attachmentsRemaining: MAX_ATTACHMENTS,
+    metadataCharactersRemaining: MAX_METADATA,
+    fileDataCharactersRemaining: MAX_FILE_CHARACTERS,
+  }
+}
+
+export function normalizeRestorableAttachmentRecord(
+  value: unknown,
+  drafts: Record<string, string>,
+  budget: AttachmentCodecBudget,
+  prioritySessionIds: readonly string[] = [],
+): { attachments: Record<string, RestorableAttachment[]>; drafts: Record<string, string> } | null {
+  if (!isRecord(value)) return null
+  const attachments: Record<string, RestorableAttachment[]> = Object.create(null)
+  const nextDrafts = { ...drafts }
+  let sessions = 0
+  const priority = [...new Set(prioritySessionIds)]
+  const prioritySet = new Set(priority)
+  const entries = [
+    ...priority.flatMap((sessionId) => Object.prototype.hasOwnProperty.call(value, sessionId)
+      ? [[sessionId, value[sessionId]] as const]
+      : []),
+    ...Object.entries(value).filter(([sessionId]) => !prioritySet.has(sessionId)),
+  ]
+  for (const [sessionId, rawAttachments] of entries) {
+    if (
+      !isSafeKey(sessionId) || !sessionId ||
+      sessionId.length > MAX_ID || !Array.isArray(rawAttachments)
+    ) continue
+    const persist = sessions++ < MAX_SESSIONS
+    const normalized: RestorableAttachment[] = []
+    for (const raw of rawAttachments) {
+      const attachment = persist && normalized.length < MAX_PER_SESSION ? normalizeAttachment(raw, budget) : undefined
+      if (attachment) normalized.push(attachment)
+      else if (nextDrafts[sessionId]) nextDrafts[sessionId] = removeAttachmentPromptTokens(nextDrafts[sessionId], raw)
+    }
+    if (normalized.length) attachments[sessionId] = normalized
+  }
+  return { attachments, drafts: nextDrafts }
+}
+
+export function serializeDraftAttachments(
+  drafts: Record<string, string>,
+  attachments: Record<string, Attachment[]>,
+  prioritySessionIds: readonly string[] = [],
+) {
+  return normalizeRestorableAttachmentRecord(attachments, drafts, createAttachmentCodecBudget(), prioritySessionIds)
+    ?? { drafts: { ...drafts }, attachments: {} }
+}
+
+export function hydrateRestorableAttachment(value: RestorableAttachment): Attachment | null {
+  let source: AttachmentSource
+  let url = value.url
+  if (value.source.type === "file") {
+    try {
+      const data = value.source.data === undefined ? undefined : base64ToBytes(value.source.data)
+      source = { type: "file", path: value.source.path, mime: value.source.mime, data }
+      if (!url && value.source.data) url = `data:${value.source.mime};base64,${value.source.data}`
+    } catch {
+      return null
+    }
+  } else {
+    source = value.source
+    if (value.source.type === "text" && !url) {
+      url = `data:text/plain;base64,${bytesToBase64(new TextEncoder().encode(value.source.value))}`
+    }
+  }
+  return { ...value, url, source }
+}
diff --git a/packages/ui/src/stores/client-state-codec.test.ts b/packages/ui/src/stores/client-state-codec.test.ts
new file mode 100644
index 00000000..f5d1012c
--- /dev/null
+++ b/packages/ui/src/stores/client-state-codec.test.ts
@@ -0,0 +1,362 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { hydrateRestorableAttachment, serializeDraftAttachments } from "./client-state-attachments-codec.ts"
+import { decodeClientSnapshot, isFutureClientSnapshot, normalizeRestorableSession } from "./client-state-codec.ts"
+
+type UnknownRecord = Record<string, unknown>
+
+const workspace = (overrides: UnknownRecord = {}): UnknownRecord => ({
+  kind: "workspace", folder: "/work", drafts: {}, attachments: {}, scrollSnapshots: {}, ...overrides,
+})
+const session = (...tabs: unknown[]) => normalizeRestorableSession({ activeTabIndex: 0, tabs })
+const snapshot = (overrides: UnknownRecord = {}) => ({
+  version: 1, revision: 1, savedAt: 1, layout: {}, session: null, ...overrides,
+})
+const attachment = (source: UnknownRecord, overrides: UnknownRecord = {}) => ({
+  id: "item", type: source.type, display: "@item",
+  url: "",
+  filename: "item",
+  mediaType: "text/plain",
+  source,
+  ...overrides,
+})
+const file = (path: string, overrides: UnknownRecord = {}) => attachment(
+  { type: "file", path, mime: "text/plain" },
+  { filename: path.split(/[\\/]/).pop() || path, ...overrides },
+)
+const firstWorkspace = (value: ReturnType<typeof normalizeRestorableSession>) => {
+  const tab = value?.tabs[0]
+  assert.ok(tab?.kind === "workspace")
+  return tab
+}
+
+it("preserves only an explicit active home view", () => {
+  assert.equal(normalizeRestorableSession({ tabs: [], activeTabIndex: -1, homeActive: true })?.homeActive, true)
+  assert.equal(normalizeRestorableSession({ tabs: [], activeTabIndex: -1, homeActive: "true" })?.homeActive, undefined)
+})
+const normalizeWorkspace = (overrides: UnknownRecord) => firstWorkspace(session(workspace(overrides)))
+
+describe("client state codec", () => {
+  it("normalizes v1 workspace state, scroll state, and a sidecar", () => {
+    const decoded = decodeClientSnapshot(snapshot({
+      revision: 7,
+      layout: { drawer: "320" },
+      session: {
+        activeTabIndex: 8,
+        tabs: [workspace({
+          type: "instance", kind: undefined, folder: "C:/work/project", occurrence: 1, projectName: "Project",
+          drafts: { session1: "unfinished prompt" },
+          scrollSnapshots: { session1: { scrollTop: 120, scrollRatio: 0.5, atBottom: false, updatedAt: 1200 } },
+          unseenIdleSince: { session1: 1100, malformed: -1 },
+          generationRecovery: { session1: "working", session2: "interrupted", malformed: "idle" },
+          expandedSessionIds: ["session1", "session1", 42],
+        }), { kind: "sidecar", sidecarId: "docs" }],
+      },
+    }))
+
+    assert.equal(decoded?.revision, 7)
+    assert.equal(decoded?.session?.activeTabIndex, 1)
+    const tab = decoded?.session?.tabs[0]
+    assert.equal(tab?.kind, "workspace")
+    if (tab?.kind !== "workspace") return
+    assert.equal(tab.occurrence, 1)
+    assert.deepEqual({ ...tab.drafts }, { session1: "unfinished prompt" })
+    assert.deepEqual({ ...tab.unseenIdleSince }, { session1: 1100 })
+    assert.deepEqual({ ...tab.generationRecovery }, { session1: "working", session2: "interrupted" })
+    assert.deepEqual(tab.expandedSessionIds, ["session1"])
+    assert.deepEqual(tab.scrollSnapshots.session1, { scrollTop: 120, scrollRatio: 0.5, atBottom: false, updatedAt: 1200 })
+    assert.deepEqual(decoded?.session?.tabs[1], { kind: "sidecar", sidecarId: "docs" })
+  })
+
+  it("rejects malformed snapshots/sessions and recognizes future envelopes", () => {
+    const cases: [string, unknown, unknown][] = [
+      ["future version", snapshot({ version: 2 }), null],
+      ["negative revision", snapshot({ revision: -1 }), null],
+      ["non-record layout", snapshot({ layout: [] }), null],
+    ]
+    for (const [label, value, expected] of cases) assert.equal(decodeClientSnapshot(value), expected, label)
+    assert.equal(isFutureClientSnapshot({ version: 2 }), true, "future envelope")
+    assert.equal(isFutureClientSnapshot({ version: 1 }), false, "current envelope")
+    assert.equal(normalizeRestorableSession({ tabs: [{ kind: "workspace" }], activeTabIndex: 0 }), null)
+    assert.equal(normalizeWorkspace({}).expandedSessionIds, undefined)
+  })
+
+  it("caps records and drops unsafe or malformed entries", () => {
+    const drafts = Object.fromEntries(Array.from({ length: 40 }, (_, index) => [`session-${index}`, `draft-${index}`]))
+    Object.defineProperty(drafts, "__proto__", { value: "unsafe", enumerable: true })
+    const tab = normalizeWorkspace({
+      drafts,
+      scrollSnapshots: {
+        valid: { scrollTop: 10, atBottom: true, updatedAt: 100 },
+        malformed: { scrollTop: Number.NaN, atBottom: false, updatedAt: 100 },
+      },
+    })
+    assert.equal(Object.keys(tab.drafts).length, 24)
+    assert.equal(Object.prototype.hasOwnProperty.call(tab.drafts, "__proto__"), false)
+    assert.deepEqual(tab.scrollSnapshots.valid, { scrollTop: 10, atBottom: true, updatedAt: 100 })
+    assert.equal(tab.scrollSnapshots.malformed, undefined)
+  })
+
+  it("remaps active tabs after filtering, including a filtered active tab", () => {
+    const cases = [
+      ["surviving active identity", 2, [{ kind: "sidecar" },
+        { kind: "sidecar", sidecarId: "first" }, { kind: "sidecar", sidecarId: "active" }], 1],
+      ["filtered active fallback", 0, [{ kind: "sidecar" }, { kind: "sidecar", sidecarId: "fallback" }], 0],
+    ] as const
+    for (const [label, activeTabIndex, tabs, expected] of cases) {
+      const normalized = normalizeRestorableSession({ activeTabIndex, tabs })
+      assert.equal(normalized?.activeTabIndex, expected, label)
+    }
+  })
+
+  it("round trips text, file, symbol, and agent attachments", () => {
+    const attachments = [
+      attachment({ type: "text", value: "alpha\nbeta\ngamma\ndelta" }, { id: "paste", type: "text", display: "pasted #1 (4 lines)" }),
+      attachment(
+        { type: "file", path: "image.png", mime: "image/png", data: new Uint8Array([1, 2]) },
+        {
+          id: "image", type: "file", display: "[Image #1]", url: "data:image/png;base64,iVBORw0KGgo=",
+          filename: "image.png", mediaType: "image/png",
+        },
+      ),
+      attachment(
+        {
+          type: "symbol", path: "src/main.ts", name: "run", kind: 12,
+          range: { start: { line: 1, char: 2 }, end: { line: 3, char: 4 } },
+        },
+        { id: "symbol", type: "symbol" },
+      ),
+      attachment({ type: "agent", name: "reviewer" }, { id: "agent", type: "agent" }),
+    ]
+    const decoded = decodeClientSnapshot(snapshot({ session: { activeTabIndex: 0, tabs: [workspace({
+      drafts: { session1: "Review [pasted #1] and [Image #1]" }, attachments: { session1: attachments },
+    })] } }))
+    const roundTripped = decodeClientSnapshot(JSON.parse(JSON.stringify(decoded)))
+    const tab = roundTripped?.session?.tabs[0]
+    assert.equal(tab?.kind, "workspace")
+    if (tab?.kind !== "workspace") return
+    assert.deepEqual(tab.attachments.session1?.map((item) => item.source.type), ["text", "file", "symbol", "agent"])
+    const restored = hydrateRestorableAttachment(tab.attachments.session1![1]!)
+    assert.deepEqual(restored?.source.type === "file" ? [...(restored.source.data ?? [])] : null,
+      [137, 80, 78, 71, 13, 10, 26, 10])
+    assert.ok(Buffer.byteLength(JSON.stringify(roundTripped), "utf8") < 1024 * 1024)
+  })
+
+  it("drops unsupported attachments but retains oversized path-backed files and exact mentions", () => {
+    const mention = "@./reports/exact report.txt"
+    const oversizedData = new Uint8Array(64 * 1024 + 1)
+    oversizedData.subarray = () => { throw new Error("oversized data must not be Base64 encoded") }
+    const large = file("./reports/exact report.txt", {
+      id: "large", display: "@exact report.txt", url: "file:///work/reports/exact%20report.txt",
+      filename: "exact report.txt", source: { type: "file", path: "./reports/exact report.txt", mime: "text/plain", data: oversizedData },
+    })
+    const unsupported = attachment({ type: "archive" }, { id: "unsupported", type: "archive", display: "@unsupported" })
+    const tab = normalizeWorkspace({
+      drafts: { session1: `Review ${mention}; remove @unsupported` }, attachments: { session1: [large, unsupported] },
+    })
+    assert.equal(tab.attachments.session1?.length, 1)
+    assert.deepEqual(tab.attachments.session1?.[0]?.source,
+      { type: "file", path: "./reports/exact report.txt", mime: "text/plain" })
+    assert.equal(tab.drafts.session1, `Review ${mention}; remove `)
+  })
+
+  it("reserves structural and active-session identity before optional strings", () => {
+    const drafts = { first: "a".repeat(32 * 1024), second: "b".repeat(32 * 1024), third: "c".repeat(32 * 1024) }
+    const normalized = normalizeRestorableSession({ activeTabIndex: 1, tabs: [
+      workspace({ folder: "/large", drafts }), { kind: "sidecar", sidecarId: "later-sidecar" },
+    ] })
+    assert.deepEqual(normalized?.tabs[1], { kind: "sidecar", sidecarId: "later-sidecar" })
+    assert.equal(normalized?.activeTabIndex, 1)
+
+    const tab = normalizeWorkspace({
+      activeParentSessionId: "parent-session", activeSessionId: "child-session", drafts,
+    })
+    assert.equal(tab.activeParentSessionId, "parent-session")
+    assert.equal(tab.activeSessionId, "child-session")
+
+    const decoded = decodeClientSnapshot(snapshot({
+      layout: Object.fromEntries(Array.from({ length: 24 }, (_, index) => [`panel-${index}`, "x".repeat(4096)])),
+      session: { activeTabIndex: 0, tabs: [{ kind: "sidecar", sidecarId: "structural-tab" }] },
+    }))
+    assert.deepEqual(decoded?.session?.tabs, [{ kind: "sidecar", sidecarId: "structural-tab" }])
+  })
+
+  it("normalizes a valid unversioned legacy snapshot to version 1", () => {
+    const legacy: UnknownRecord = snapshot({ session: { activeTabIndex: 0, tabs: [workspace()] } })
+    delete legacy.version
+    const decoded = decodeClientSnapshot(legacy)
+    assert.equal(decoded?.version, 1)
+    assert.equal(decoded?.session?.tabs[0]?.kind, "workspace")
+    assert.equal(decodeClientSnapshot({ ...legacy, version: 2 }), null)
+  })
+
+  for (const [label, activeSessionId] of [
+    ["active session", "active-session"],
+    ["active no-session prompt", "__no_session_draft__"],
+  ] as const) {
+    it(`retains the ${label} draft beyond the per-tab entry budget`, () => {
+      const drafts = Object.fromEntries([
+        ...Array.from({ length: 24 }, (_, index) => [`older-${index}`, `draft-${index}`]),
+        [activeSessionId, "unsent active draft"],
+      ])
+      const tab = normalizeRestorableSession({ activeTabIndex: 0, tabs: [workspace({
+        activeSessionId: activeSessionId === "__no_session_draft__" ? undefined : activeSessionId,
+        drafts,
+      })] })?.tabs[0]
+
+      assert.equal(tab?.kind === "workspace" ? tab.drafts[activeSessionId] : undefined, "unsent active draft")
+      assert.equal(tab?.kind === "workspace" ? Object.keys(tab.drafts).length : 0, 24)
+    })
+  }
+
+  it("retains the active tab draft before earlier tabs consume the string budget", () => {
+    const normalized = normalizeRestorableSession({ activeTabIndex: 1, tabs: [
+      workspace({ drafts: {
+        first: "a".repeat(32 * 1024), second: "b".repeat(32 * 1024), third: "c".repeat(32 * 1024),
+      } }),
+      workspace({ folder: "/active", activeSessionId: "active", drafts: { active: "keep me" } }),
+    ] })
+    const active = normalized?.tabs[1]
+
+    assert.equal(active?.kind === "workspace" ? active.drafts.active : undefined, "keep me")
+    assert.equal(normalized?.activeTabIndex, 1)
+  })
+
+  it("retains the active tab draft before inactive tab identities consume the string budget", () => {
+    const normalized = normalizeRestorableSession({ activeTabIndex: 24, tabs: [
+      ...Array.from({ length: 24 }, (_, index) => workspace({ folder: `${index}${"x".repeat(4095)}` })),
+      workspace({ folder: "/active", activeSessionId: "active", drafts: { active: "keep me" } }),
+    ] })
+    const active = normalized?.tabs.find((tab) => tab.kind === "workspace" && tab.folder === "/active")
+
+    assert.equal(active?.kind === "workspace" ? active.drafts.active : undefined, "keep me")
+    assert.equal(normalized?.tabs[normalized.activeTabIndex], active)
+  })
+
+  it("reserves inactive tab identities and selected drafts before active payloads", () => {
+    const normalized = normalizeRestorableSession({ activeTabIndex: 0, tabs: [
+      workspace({ drafts: {
+        first: "a".repeat(32 * 1024), second: "b".repeat(32 * 1024), third: "c".repeat(32 * 1024),
+      } }),
+      workspace({ folder: "/inactive", activeParentSessionId: "parent", activeSessionId: "selected",
+        drafts: Object.fromEntries([
+          ...Array.from({ length: 24 }, (_, index) => [`older-${index}`, `draft-${index}`]),
+          ["selected", "keep inactive"],
+        ]) }),
+    ] })
+    const inactive = normalized?.tabs.find((tab) => tab.kind === "workspace" && tab.folder === "/inactive")
+
+    assert.equal(inactive?.kind === "workspace" ? inactive.activeParentSessionId : undefined, "parent")
+    assert.equal(inactive?.kind === "workspace" ? inactive.activeSessionId : undefined, "selected")
+    assert.equal(inactive?.kind === "workspace" ? inactive.drafts.selected : undefined, "keep inactive")
+  })
+
+  it("retains active-session attachments beyond the per-tab session budget", () => {
+    const activeAttachment = file("active.png", { id: "active-image", display: "[Image #1]", mediaType: "image/png" })
+    const attachments = Object.fromEntries([
+      ...Array.from({ length: 24 }, (_, index) => [`older-${index}`, [file(`older-${index}.txt`)]]),
+      ["active", [activeAttachment]],
+    ])
+    const tab = normalizeRestorableSession({ activeTabIndex: 0, tabs: [workspace({
+      activeSessionId: "active",
+      drafts: { active: "Review [Image #1]" },
+      attachments,
+    })] })?.tabs[0]
+
+    assert.equal(tab?.kind === "workspace" ? tab.attachments.active?.[0]?.id : undefined, "active-image")
+    assert.equal(tab?.kind === "workspace" ? tab.drafts.active : undefined, "Review [Image #1]")
+  })
+
+  it("reserves inactive selected attachments before active optional attachments", () => {
+    const activeAttachments = Object.fromEntries(Array.from({ length: 8 }, (_, sessionIndex) => [
+      `active-${sessionIndex}`,
+      Array.from({ length: 8 }, (_, attachmentIndex) => file(`active-${sessionIndex}-${attachmentIndex}.txt`)),
+    ]))
+    const selected = file("inactive.txt", { id: "inactive-selected", display: "@inactive.txt" })
+    const normalized = normalizeRestorableSession({ activeTabIndex: 0, tabs: [
+      workspace({ activeSessionId: "active-0", drafts: { "active-0": "active" }, attachments: activeAttachments }),
+      workspace({ folder: "/inactive", activeSessionId: "selected", drafts: { selected: "Review @inactive.txt" },
+        attachments: { selected: [selected] } }),
+    ] })
+    const inactive = normalized?.tabs.find((tab) => tab.kind === "workspace" && tab.folder === "/inactive")
+
+    assert.equal(inactive?.kind === "workspace" ? inactive.attachments.selected?.[0]?.id : undefined, "inactive-selected")
+  })
+
+  it("prioritizes active attachments during capture serialization", () => {
+    const activeAttachment = file("active.png", { id: "active-image", display: "[Image #1]", mediaType: "image/png" })
+    const attachments = Object.fromEntries([
+      ...Array.from({ length: 24 }, (_, index) => [`older-${index}`, [file(`older-${index}.txt`)]]),
+      ["active", [activeAttachment]],
+    ]) as never
+    const captured = serializeDraftAttachments({ active: "Review [Image #1]" }, attachments, ["active"])
+
+    assert.equal(captured.attachments.active?.[0]?.id, "active-image")
+    assert.equal(captured.drafts.active, "Review [Image #1]")
+  })
+
+  it("does not let malformed tabs consume the identity budget", () => {
+    const normalized = normalizeRestorableSession({ activeTabIndex: 24, tabs: [
+      ...Array.from({ length: 24 }, () => workspace({ folder: "x".repeat(4096), drafts: [] })),
+      { kind: "sidecar", sidecarId: "valid-late-tab" },
+    ] })
+    assert.deepEqual(normalized, { tabs: [{ kind: "sidecar", sidecarId: "valid-late-tab" }], activeTabIndex: 0 })
+  })
+
+  it("removes every picker mention for attachments beyond the per-session limit", () => {
+    const cases = [
+      ["relative file", "./dir/f8", "f8", "@f8",
+        ["@./dir/f8", "@f8"], ["@./dir/f80", "@f80"], "text/plain"],
+      ["absolute file", "/var/work/f8.ts", "f8.ts", "@f8.ts",
+        ["@/var/work/f8.ts", "@f8.ts"], ["@/var/work/f8.ts.bak", "@f8.tsx"], "text/plain"],
+      ["Windows regex characters", "C:\\work\\[draft](8).ts", "[draft](8).ts", "@[draft](8).ts",
+        ["@C:\\work\\[draft](8).ts", "@[draft](8).ts"],
+        ["@C:\\work\\[draft](8).tsx", "@[draft](8).tsx"], "text/plain"],
+      ["raw spaced path", "./dir/my file.ts", "my file.ts", "@my file.ts",
+        ["@./dir/my file.ts", "@my file.ts"], ["@./dir/my file.tsx", "@my file.tsx"], "text/plain"],
+      ["relative directory", "./dir/nested", "nested/", "@nested/",
+        ["@dir/nested/", "@nested/"], ["@dir/nested/other", "@nested/other"], "inode/directory"],
+    ] as const
+    for (const [label, path, filename, display, tokens, collisions, mime] of cases) {
+      const keep = Array.from({ length: 8 }, (_, index) => file(`./keep/${index}`, { id: `keep-${index}` }))
+      const tab = normalizeWorkspace({
+        drafts: { session: `remove ${tokens.join(" then ")} keep ${collisions.join(" and ")} and @other` },
+        attachments: { session: [...keep, file(path, { id: "drop", filename, display,
+          mediaType: mime, source: { type: "file", path, mime } })] },
+      })
+      assert.equal(tab.attachments.session?.length, 8, label)
+      assert.equal(tab.drafts.session, `remove  then  keep ${collisions.join(" and ")} and @other`, label)
+    }
+  })
+
+  it("removes loose dropped placeholders without touching ordinary bracket text", () => {
+    const input = [
+      "[Image #9]", "[ Image # 9 ]", "[iMaGe # 9]", "Image #9",
+      "[Image #90]", "[Image #9 notes]",
+      "[pasted #4]", "[ pasted # 4 ]", "[PaStEd # 4]", "pasted #4",
+      "[pasted #40]", "[pasted notes]", "[ordinary bracket text]",
+    ].join("|")
+    const dropped = [
+      file("large.png", { id: "image", display: "[Image #9]", mediaType: "image/png",
+        source: { type: "file", path: "large.png", mime: "image/png", data: new Uint8Array(65 * 1024) } }),
+      attachment({ type: "text", value: "x".repeat(24 * 1024 + 1) }, { id: "paste", type: "text", display: "pasted #4 (4 lines)" }),
+      attachment({ type: "archive" }, { id: "ordinary", type: "archive", display: "[ordinary bracket text]" }),
+    ]
+    const tab = normalizeWorkspace({ drafts: { session1: input }, attachments: { session1: dropped } })
+    assert.deepEqual({ ...tab.attachments }, {})
+    assert.equal(tab.drafts.session1,
+      "|||Image #9|[Image #90]|[Image #9 notes]||||pasted #4|[pasted #40]|[pasted notes]|[ordinary bracket text]")
+  })
+
+  it("keeps a maximal normalized attachment snapshot below the native 1 MiB limit", () => {
+    const normalized = session(...Array.from({ length: 32 }, (_, index) => workspace({
+      folder: `/work/${index}`, drafts: { session: `[Image #${index + 1}]` },
+      attachments: { session: [file(`file-${index}.bin`, { id: `file-${index}`, display: `[Image #${index + 1}]`,
+        mediaType: "application/octet-stream", source: { type: "file", path: `file-${index}.bin`,
+          mime: "application/octet-stream", data: new Uint8Array(64 * 1024) } })] },
+    })))
+    assert.ok(normalized)
+    assert.ok(Buffer.byteLength(JSON.stringify(normalized), "utf8") < 1024 * 1024)
+  })
+})
diff --git a/packages/ui/src/stores/client-state-codec.ts b/packages/ui/src/stores/client-state-codec.ts
new file mode 100644
index 00000000..1ca55118
--- /dev/null
+++ b/packages/ui/src/stores/client-state-codec.ts
@@ -0,0 +1,302 @@
+import type { ScrollSnapshot } from "./message-v2/types"
+import { createAttachmentCodecBudget, normalizeRestorableAttachmentRecord,
+  type AttachmentCodecBudget, type RestorableAttachment } from "./client-state-attachments-codec"
+import type { PersistedGenerationRecovery } from "./session-generation-recovery"
+
+export interface RestorableWorkspaceTabState {
+  kind: "workspace"; folder: string; occurrence?: number; projectName?: string; binaryPath?: string
+  activeParentSessionId?: string; activeSessionId?: string
+  drafts: Record<string, string>; attachments: Record<string, RestorableAttachment[]>
+  scrollSnapshots: Record<string, ScrollSnapshot>; unseenIdleSince: Record<string, number>
+  generationRecovery: Record<string, PersistedGenerationRecovery>
+  expandedSessionIds?: string[]
+}
+
+export interface RestorableSidecarTabState { kind: "sidecar"; sidecarId: string }
+export type RestorableTabState = RestorableWorkspaceTabState | RestorableSidecarTabState
+export interface RestorableSessionState { tabs: RestorableTabState[]; activeTabIndex: number; homeActive?: boolean }
+export interface ClientSnapshotV1 {
+  version: 1; revision: number; savedAt: number
+  layout: Record<string, string>; session: RestorableSessionState | null
+}
+
+const MAX_TABS = 32, MAX_LAYOUT_ENTRIES = 64, MAX_DRAFTS = 24, MAX_SCROLLS_PER_TAB = 96
+const MAX_IDLE_MARKERS = 256, MAX_RECOVERY = 256, MAX_EXPANDED = 256, MAX_KEY = 256, MAX_PATH = 4096, MAX_ID = 512
+const MAX_LAYOUT_VALUE = 4096, MAX_DRAFT = 32 * 1024, MAX_ANCHOR_KEY = 1024
+const MAX_STRINGS = 96 * 1024, MAX_SCROLLS = 256
+const NO_SESSION_DRAFT_SESSION_ID = "__no_session_draft__"
+
+interface StringBudget { remaining: number; scrollSnapshotsRemaining: number; attachments: AttachmentCodecBudget }
+
+function createBudget(): StringBudget {
+  return { remaining: MAX_STRINGS, scrollSnapshotsRemaining: MAX_SCROLLS, attachments: createAttachmentCodecBudget() }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+const safeKey = (key: string) => key !== "__proto__" && key !== "constructor" && key !== "prototype"
+
+function takeString(value: unknown, max: number, budget: StringBudget, allowEmpty = false): string | undefined {
+  if (typeof value !== "string" || value.length > max || value.length > budget.remaining) return
+  if (!allowEmpty && value.trim().length === 0) return
+  budget.remaining -= value.length
+  return value
+}
+
+const takeNumber = (value: unknown, min: number, max: number): number | undefined =>
+  typeof value === "number" && Number.isFinite(value) && value >= min && value <= max ? value : undefined
+
+function normalizeRecord<T>(
+  value: unknown, max: number, budget: StringBudget,
+  normalize: (value: unknown) => T | undefined,
+  accept: (value: unknown) => boolean = () => true,
+  accepted: () => void = () => {},
+  priorityKeys: readonly string[] = [],
+): Record<string, T> | null {
+  if (!isRecord(value)) return null
+  const result: Record<string, T> = Object.create(null)
+  let count = 0
+  const priorities = [...new Set(priorityKeys)]
+  const prioritySet = new Set(priorities)
+  const entries = [
+    ...priorities.flatMap((key) => Object.prototype.hasOwnProperty.call(value, key) ? [[key, value[key]] as const] : []),
+    ...Object.entries(value).filter(([key]) => !prioritySet.has(key)),
+  ]
+  for (const [rawKey, rawValue] of entries) {
+    if (count >= max) break
+    if (!safeKey(rawKey) || !accept(rawValue)) continue
+    const key = takeString(rawKey, MAX_KEY, budget)
+    const entry = normalize(rawValue)
+    if (key === undefined || entry === undefined) continue
+    result[key] = entry
+    count += 1
+    accepted()
+  }
+  return result
+}
+
+function normalizeStringRecord(
+  value: unknown,
+  max: number,
+  valueMax: number,
+  budget: StringBudget,
+  priorityKeys: readonly string[] = [],
+) {
+  return normalizeRecord(value, max, budget, (entry) => takeString(entry, valueMax, budget, true),
+    undefined, undefined, priorityKeys)
+}
+
+function normalizeScrollSnapshot(value: unknown, budget: StringBudget): ScrollSnapshot | undefined {
+  if (!isRecord(value)) return
+  const scrollTop = takeNumber(value.scrollTop, 0, 1_000_000_000)
+  const updatedAt = takeNumber(value.updatedAt, 0, Number.MAX_SAFE_INTEGER)
+  if (scrollTop === undefined || updatedAt === undefined || typeof value.atBottom !== "boolean") return
+  const result: ScrollSnapshot = { scrollTop, atBottom: value.atBottom, updatedAt }
+  const scrollRatio = takeNumber(value.scrollRatio, 0, 1)
+  const maxScrollTop = takeNumber(value.maxScrollTop, 0, 1_000_000_000)
+  const anchorOffset = takeNumber(value.anchorOffset, -1_000_000, 1_000_000)
+  const anchorKey = value.anchorKey === undefined ? undefined : takeString(value.anchorKey, MAX_ANCHOR_KEY, budget)
+  if (scrollRatio !== undefined) result.scrollRatio = scrollRatio
+  if (maxScrollTop !== undefined) result.maxScrollTop = maxScrollTop
+  if (anchorKey !== undefined) result.anchorKey = anchorKey
+  if (anchorOffset !== undefined) result.anchorOffset = anchorOffset
+  if (value.followModeType === "following" || value.followModeType === "escaped") result.followModeType = value.followModeType
+  return result
+}
+
+function normalizeExpandedSessionIds(value: unknown, budget: StringBudget): string[] | null {
+  if (!Array.isArray(value)) return null
+  const result: string[] = []
+  const seen = new Set<string>()
+  for (const entry of value.slice(0, MAX_EXPANDED)) {
+    if (typeof entry !== "string" || seen.has(entry)) continue
+    const id = takeString(entry, MAX_ID, budget)
+    if (id === undefined) continue
+    seen.add(id)
+    result.push(id)
+  }
+  return result
+}
+
+function normalizeWorkspaceTab(
+  value: Record<string, unknown>,
+  identity: WorkspaceIdentity,
+  budget: StringBudget,
+  _prioritizeDrafts: boolean,
+): RestorableWorkspaceTabState | null {
+  const reservedDrafts = identity.priorityDrafts
+  const remainingDrafts = Object.fromEntries(Object.entries(value.drafts ?? {})
+    .filter(([id]) => !Object.prototype.hasOwnProperty.call(reservedDrafts, id)))
+  const additionalDrafts = normalizeStringRecord(
+    remainingDrafts,
+    Math.max(0, MAX_DRAFTS - Object.keys(reservedDrafts).length),
+    MAX_DRAFT,
+    budget,
+  )
+  const drafts = additionalDrafts ? { ...reservedDrafts, ...additionalDrafts } : null
+  const scrollLimit = Math.min(MAX_SCROLLS_PER_TAB, budget.scrollSnapshotsRemaining)
+  const scrollSnapshots = normalizeRecord(value.scrollSnapshots ?? {}, scrollLimit, budget,
+    (entry) => normalizeScrollSnapshot(entry, budget), undefined,
+    () => { budget.scrollSnapshotsRemaining -= 1 })
+  const unseenIdleSince = normalizeRecord(value.unseenIdleSince ?? {}, MAX_IDLE_MARKERS, budget,
+    (entry) => takeNumber(entry, 0, Number.MAX_SAFE_INTEGER))
+  const generationRecovery = normalizeRecord<PersistedGenerationRecovery>(
+    value.generationRecovery ?? {}, MAX_RECOVERY, budget,
+    (entry) => entry as PersistedGenerationRecovery,
+    (entry) => entry === "working" || entry === "interrupted")
+  const expandedSessionIds = value.expandedSessionIds === undefined
+    ? undefined
+    : normalizeExpandedSessionIds(value.expandedSessionIds, budget)
+  if (!drafts || !scrollSnapshots || !unseenIdleSince || !generationRecovery || expandedSessionIds === null) return null
+  const remainingAttachments = Object.fromEntries(Object.entries(value.attachments ?? {})
+    .filter(([id]) => !identity.prioritySessionIds.includes(id)))
+  const attachmentResult = normalizeRestorableAttachmentRecord(
+    remainingAttachments, drafts, budget.attachments,
+  )
+  if (!attachmentResult) return null
+
+  const result: RestorableWorkspaceTabState = {
+    kind: "workspace", folder: identity.folder,
+    drafts: attachmentResult.drafts,
+    attachments: { ...identity.priorityAttachments, ...attachmentResult.attachments },
+    scrollSnapshots, unseenIdleSince, generationRecovery,
+  }
+  if (expandedSessionIds !== undefined) result.expandedSessionIds = expandedSessionIds
+  if (Number.isInteger(value.occurrence) && Number(value.occurrence) >= 0 && Number(value.occurrence) < MAX_TABS) {
+    result.occurrence = Number(value.occurrence)
+  }
+  const projectName = value.projectName === undefined ? undefined : takeString(value.projectName, MAX_PATH, budget)
+  const binaryPath = value.binaryPath === undefined ? undefined : takeString(value.binaryPath, MAX_PATH, budget)
+  if (projectName !== undefined) result.projectName = projectName
+  if (binaryPath !== undefined) result.binaryPath = binaryPath
+  if (identity.activeParentSessionId !== undefined) result.activeParentSessionId = identity.activeParentSessionId
+  if (identity.activeSessionId !== undefined) result.activeSessionId = identity.activeSessionId
+  return result
+}
+
+interface WorkspaceIdentity {
+  kind: "workspace"; value: Record<string, unknown>; folder: string
+  activeParentSessionId?: string; activeSessionId?: string
+  prioritySessionIds: string[]; priorityDrafts: Record<string, string>
+  priorityAttachments: Record<string, RestorableAttachment[]>
+}
+type TabIdentity = WorkspaceIdentity | RestorableSidecarTabState
+
+function normalizeIdentity(value: unknown, budget: StringBudget): TabIdentity | null {
+  if (!isRecord(value)) return null
+  const kind = value.kind ?? value.type
+  if (kind === "sidecar") {
+    const sidecarId = takeString(value.sidecarId, MAX_ID, budget)
+    return sidecarId === undefined ? null : { kind, sidecarId }
+  }
+  if (kind !== "workspace" && kind !== "instance") return null
+  if (!["drafts", "attachments", "scrollSnapshots", "unseenIdleSince", "generationRecovery"]
+    .every((key) => isRecord(value[key] ?? {}))) return null
+  const folder = takeString(value.folder, MAX_PATH, budget)
+  if (folder === undefined) return null
+  const activeParentSessionId = value.activeParentSessionId === undefined ? undefined
+    : takeString(value.activeParentSessionId, MAX_ID, budget)
+  const activeSessionId = value.activeSessionId === undefined ? undefined : takeString(value.activeSessionId, MAX_ID, budget)
+  const prioritySessionIds = [activeSessionId, NO_SESSION_DRAFT_SESSION_ID]
+    .filter((id): id is string => Boolean(id))
+  return {
+    kind: "workspace", value, folder, activeParentSessionId, activeSessionId,
+    prioritySessionIds, priorityDrafts: Object.create(null), priorityAttachments: Object.create(null),
+  }
+}
+
+function reservePriorityDrafts(identity: WorkspaceIdentity, budget: StringBudget): void {
+  const drafts = identity.value.drafts ?? {}
+  if (!isRecord(drafts)) return
+  for (const rawKey of identity.prioritySessionIds) {
+    if (!safeKey(rawKey) || !Object.prototype.hasOwnProperty.call(drafts, rawKey)) continue
+    const remaining = budget.remaining
+    const key = takeString(rawKey, MAX_KEY, budget)
+    const draft = takeString(drafts[rawKey], MAX_DRAFT, budget, true)
+    if (key === undefined || draft === undefined) {
+      budget.remaining = remaining
+      continue
+    }
+    identity.priorityDrafts[key] = draft
+  }
+  const attachments = identity.value.attachments ?? {}
+  if (!isRecord(attachments)) return
+  const priorityAttachments = Object.fromEntries(identity.prioritySessionIds
+    .filter((id) => Object.prototype.hasOwnProperty.call(attachments, id))
+    .map((id) => [id, attachments[id]]))
+  const result = normalizeRestorableAttachmentRecord(
+    priorityAttachments,
+    identity.priorityDrafts,
+    budget.attachments,
+    identity.prioritySessionIds,
+  )
+  if (!result) return
+  identity.priorityDrafts = result.drafts
+  identity.priorityAttachments = result.attachments
+}
+
+export function normalizeRestorableSession(value: unknown): RestorableSessionState | null {
+  return normalizeSession(value, createBudget())
+}
+
+function normalizeSession(value: unknown, budget: StringBudget): RestorableSessionState | null {
+  if (!isRecord(value) || !Array.isArray(value.tabs) || !Number.isInteger(value.activeTabIndex)) return null
+  const requested = Number(value.activeTabIndex)
+  const rawTabs = value.tabs.slice(0, MAX_TABS)
+  const identityByIndex = new Map<number, TabIdentity>()
+  const normalizedByIndex = new Map<number, RestorableTabState>()
+  const normalizeIdentityAt = (originalIndex: number) => {
+    const identity = normalizeIdentity(rawTabs[originalIndex], budget)
+    if (!identity) return
+    identityByIndex.set(originalIndex, identity)
+  }
+  const normalizeTabAt = (originalIndex: number, prioritizeDrafts: boolean) => {
+    const identity = identityByIndex.get(originalIndex)
+    if (!identity) return
+    const tab = identity.kind === "sidecar"
+      ? identity
+      : normalizeWorkspaceTab(identity.value, identity, budget, prioritizeDrafts)
+    if (tab) normalizedByIndex.set(originalIndex, tab)
+  }
+  rawTabs.forEach((_tab, index) => normalizeIdentityAt(index))
+  const priorityOrder = [requested, ...rawTabs.map((_tab, index) => index).filter((index) => index !== requested)]
+  for (const index of priorityOrder) {
+    const identity = identityByIndex.get(index)
+    if (identity?.kind === "workspace") reservePriorityDrafts(identity, budget)
+  }
+  if (rawTabs[requested] !== undefined) normalizeTabAt(requested, true)
+  rawTabs.forEach((_tab, index) => {
+    if (index !== requested) normalizeTabAt(index, true)
+  })
+  const identities = rawTabs.flatMap((_tab, originalIndex) => {
+    const identity = identityByIndex.get(originalIndex)
+    return identity ? [{ originalIndex, identity }] : []
+  })
+  const normalized = identities.flatMap(({ originalIndex }) => {
+    const tab = normalizedByIndex.get(originalIndex)
+    return tab ? [{ originalIndex, tab }] : []
+  })
+  if (value.tabs.length && !normalized.length) return null
+
+  const tabs = normalized.map(({ tab }) => tab)
+  const surviving = normalized.findIndex(({ originalIndex }) => originalIndex === requested)
+  const next = normalized.findIndex(({ originalIndex }) => originalIndex > requested)
+  const activeTabIndex = !tabs.length ? -1 : surviving >= 0 ? surviving : next >= 0 ? next : tabs.length - 1
+  return { tabs, activeTabIndex, ...(value.homeActive === true ? { homeActive: true } : {}) }
+}
+
+export function decodeClientSnapshot(value: unknown): ClientSnapshotV1 | null {
+  if (!isRecord(value) || (value.version !== undefined && value.version !== 1)
+    || !Number.isSafeInteger(value.revision) || Number(value.revision) < 0) return null
+  const savedAt = takeNumber(value.savedAt, 0, Number.MAX_SAFE_INTEGER)
+  if (savedAt === undefined) return null
+  const budget = createBudget()
+  const session = value.session === null ? null : normalizeSession(value.session, budget)
+  if (value.session !== null && !session) return null
+  const layout = normalizeStringRecord(value.layout, MAX_LAYOUT_ENTRIES, MAX_LAYOUT_VALUE, budget)
+  return layout ? { version: 1, revision: Number(value.revision), savedAt, layout, session } : null
+}
+
+export function isFutureClientSnapshot(value: unknown): boolean {
+  return isRecord(value) && typeof value.version === "number" && Number.isInteger(value.version) && value.version > 1
+}
diff --git a/packages/ui/src/stores/client-state.test.ts b/packages/ui/src/stores/client-state.test.ts
new file mode 100644
index 00000000..882a9234
--- /dev/null
+++ b/packages/ui/src/stores/client-state.test.ts
@@ -0,0 +1,250 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+type ClientState = typeof import("./client-state.ts")
+type NativeApi = Record<string, (...args: any[]) => any>; type TransactionKind = "clear" | "disable"
+const layoutKey = "opencode-session-sidebar-width-v8"; let moduleId = 0
+class MemoryStorage {
+  private readonly values = new Map<string, string>()
+  get length() { return this.values.size }; clear() { this.values.clear() }
+  getItem(key: string) { return this.values.get(key) ?? null }
+  key(index: number) { return [...this.values.keys()][index] ?? null }
+  removeItem(key: string) { this.values.delete(key) }
+  setItem(key: string, value: string) { this.values.set(key, String(value)) }
+}
+const session = (sidecarId: string) => ({ tabs: [{ kind: "sidecar" as const, sidecarId }], activeTabIndex: 0 })
+const snapshot = (sidecarId: string, layout: Record<string, string> = {}) => ({ version: 1, revision: 1, savedAt: 1, layout, session: session(sidecarId) })
+const loadResult = (saved: unknown = null, isPrimary = true) => ({ isPrimary, restoreEnabled: true, snapshot: saved })
+const deferred = <T>() => {
+  let resolve!: (value: T) => void, reject!: (error: Error) => void
+  const promise = new Promise<T>((yes, no) => { resolve = yes; reject = no })
+  return { promise, reject, resolve }
+}
+const installWindow = (api?: NativeApi, storage = new MemoryStorage()) => {
+  Object.defineProperty(globalThis, "window", { configurable: true, value: api
+    ? { __CODENOMAD_RUNTIME_HOST__: "electron", __CODENOMAD_WINDOW_CONTEXT__: "local", localStorage: storage, electronAPI: api }
+    : { localStorage: storage } })
+  return storage
+}
+const boot = async (api?: NativeApi, storage?: MemoryStorage) => {
+  installWindow(api ? { claimClientStateAccess: async () => true, ...api } : undefined, storage)
+  const state = await import(`./client-state.ts?test=${moduleId++}`) as ClientState
+  await state.initializeClientState()
+  return state
+}
+const transact = (state: ClientState, kind: TransactionKind) => kind === "clear"
+  ? state.clearRestoredClientState() : state.setRestorePreviousStateEnabled(false)
+describe("client state ownership and persistence", () => {
+  it("treats a rejected access claim as secondary without loading", async () => {
+    let loads = 0
+    const state = await boot({
+      claimClientStateAccess: async () => { throw new Error("claim rejected") },
+      loadClientState: async () => { loads += 1; return loadResult() },
+    })
+    assert.equal(state.clientStateIsPrimary(), false)
+    assert.equal(loads, 0)
+  })
+  it("claims before loading and reuses one renderer token for native operations", async () => {
+    const storage = new MemoryStorage()
+    storage.setItem(layoutKey, "360")
+    const calls: Array<{ operation: string; token: string }> = [], saved: any[] = []
+    const state = await boot({
+      claimClientStateAccess: async (token) => { calls.push({ operation: "claim", token }); return true },
+      loadClientState: async (token) => { calls.push({ operation: "load", token }); return loadResult() },
+      saveClientState: async (token, value) => { calls.push({ operation: "save", token }); saved.push(value); return true },
+      setClientStateRestoreEnabled: async (token, enabled) => { calls.push({ operation: `set:${enabled}`, token }); return true },
+    }, storage)
+    assert.equal(state.readClientLayoutValue(layoutKey), "360")
+    state.updateRestorableSession(session("project")); await state.flushClientState()
+    state.writeClientLayoutValue(layoutKey, "500"); await state.flushClientState()
+    assert.deepEqual(saved.map(({ revision }) => revision), [1, 2])
+    assert.equal(saved[0].version, 1)
+    assert.equal(saved[0].layout[layoutKey], "360")
+    assert.equal(saved[0].session.tabs[0].sidecarId, "project")
+    await state.setRestorePreviousStateEnabled(false)
+    assert.equal(state.restorePreviousStateEnabled(), false)
+    assert.equal(state.loadedRestorableSession(), null)
+    assert.equal(storage.getItem(layoutKey), null)
+    assert.deepEqual(calls.map(({ operation }) => operation), ["claim", "load", "save", "save", "set:false"])
+    assert.match(calls[0]!.token, /^[0-9a-f]{64}$/)
+    assert.ok(calls.every(({ token }) => token === calls[0]!.token))
+    assert.equal(storage.getItem(calls[0]!.token), null)
+  })
+})
+const destructiveContract = async (kind: TransactionKind, inFlightSave: boolean) => {
+  const operation = deferred<boolean>(), started = deferred<void>()
+  const saved: any[] = [], preferences: boolean[] = []
+  const api: NativeApi = {
+    loadClientState: async () => loadResult(!inFlightSave && kind === "clear" ? snapshot("saved") : null),
+    saveClientState: (_token, value) => {
+      saved.push(value)
+      if (!inFlightSave || saved.length > 1) return Promise.resolve(true)
+      started.resolve(); return operation.promise
+    },
+  }
+  api[kind === "clear" ? "clearClientState" : "setClientStateRestoreEnabled"] = (...args: any[]) => {
+    if (kind === "disable") preferences.push(args[1])
+    if (inFlightSave) throw new Error(`native ${kind} failed`)
+    started.resolve(); return operation.promise
+  }
+  const state = await boot(api)
+  if (inFlightSave) {
+    state.updateRestorableSession(session("retry"))
+    const firstFlush = state.flushClientState()
+    await started.promise
+    const transaction = transact(state, kind)
+    operation.reject(new Error("first save failed"))
+    await assert.rejects(firstFlush, /first save failed/)
+    await assert.rejects(transaction, new RegExp(`native ${kind} failed`))
+  } else {
+    const transaction = transact(state, kind)
+    await started.promise
+    state.updateRestorableSession(session("buffered"))
+    state.writeClientLayoutValue(layoutKey, "430")
+    operation.reject(new Error(`native ${kind} failed`))
+    await assert.rejects(transaction, new RegExp(`native ${kind} failed`))
+  }
+  assert.equal(state.restorePreviousStateEnabled(), true)
+  if (kind === "disable") assert.deepEqual(preferences, [false])
+  await state.flushClientState()
+  assert.equal(saved.length, inFlightSave ? 2 : 1)
+  assert.equal(saved.at(-1).session.tabs[0].sidecarId, inFlightSave ? "retry" : "buffered")
+  if (!inFlightSave) assert.equal(saved[0].layout[layoutKey], "430")
+}
+describe("failed destructive transactions", () => {
+  for (const kind of ["clear", "disable"] as const) {
+    it(`${kind}: rolls back and persists mutations buffered during delayed failure`, () => destructiveContract(kind, false))
+    it(`${kind}: preserves retry dirt from an in-flight failed save`, () => destructiveContract(kind, true))
+  }
+})
+describe("future envelopes and clear races", () => {
+  it("serializes overlapping clear and disable transactions without stranding writes", async () => {
+    const clear = deferred<boolean>(), disable = deferred<boolean>()
+    const clearStarted = deferred<void>(), disableStarted = deferred<void>()
+    const operations: string[] = [], saved: any[] = []
+    const state = await boot({
+      loadClientState: async () => loadResult(snapshot("saved")),
+      clearClientState: async () => { operations.push("clear"); clearStarted.resolve(); return clear.promise },
+      setClientStateRestoreEnabled: async (_token, enabled) => {
+        operations.push(`restore:${enabled}`)
+        if (!enabled) disableStarted.resolve()
+        return enabled ? true : disable.promise
+      },
+      saveClientState: async (_token, value) => { saved.push(value); return true },
+    })
+    const clearing = state.clearRestoredClientState()
+    let sameValueSettled = false
+    const sameValueEnable = state.setRestorePreviousStateEnabled(true).then(() => { sameValueSettled = true })
+    const disabling = state.setRestorePreviousStateEnabled(false)
+    const secondClear = state.clearRestoredClientState()
+    const enabling = state.setRestorePreviousStateEnabled(true)
+    await clearStarted.promise
+    assert.deepEqual(operations, ["clear"], "disable waits for clear ownership")
+    assert.equal(sameValueSettled, false, "same-value enable waits for prior transition")
+    clear.resolve(true); await clearing; await sameValueEnable; await disableStarted.promise
+    assert.deepEqual(operations, ["clear", "restore:true", "restore:false"])
+    disable.resolve(true); await disabling; await secondClear; await enabling
+    assert.deepEqual(operations, ["clear", "restore:true", "restore:false", "clear", "restore:true"])
+    state.updateRestorableSession(session("after-overlap")); await state.flushClientState()
+    assert.equal(saved.at(-1).session.tabs[0].sidecarId, "after-overlap")
+  })
+
+  it("clears a future envelope while suppressing recapture for the run", async () => {
+    let clears = 0, saves = 0
+    const state = await boot({
+      loadClientState: async () => loadResult({ version: 2, future: true }),
+      saveClientState: async () => { saves += 1; return true },
+      clearClientState: async () => { clears += 1; return true },
+    })
+    state.writeClientLayoutValue(layoutKey, "350"); state.updateRestorableSession(session("docs"))
+    await state.flushClientState(); await state.clearRestoredClientState()
+    state.writeClientLayoutValue(layoutKey, "360"); state.updateRestorableSession(session("new"))
+    await state.flushClientState()
+    assert.equal(clears, 1)
+    assert.equal(saves, 0)
+  })
+  it("keeps ownership of a future envelope after disable is rejected", async () => {
+    let clears = 0
+    const state = await boot({
+      loadClientState: async () => loadResult({ version: 2, future: true }),
+      setClientStateRestoreEnabled: async () => false,
+      clearClientState: async () => { clears += 1; return true },
+    })
+    await assert.rejects(state.setRestorePreviousStateEnabled(false), /update was rejected/)
+    assert.equal(state.restorePreviousStateEnabled(), true)
+    assert.equal(state.clientStateIsPrimary(), true)
+    await state.clearRestoredClientState()
+    assert.equal(state.clientStateIsPrimary(), true)
+    assert.equal(clears, 1)
+  })
+  it("blocks captures before an in-flight clear reaches the native host", async () => {
+    const clear = deferred<boolean>(); let saves = 0
+    const state = await boot({
+      loadClientState: async () => loadResult(snapshot("saved")),
+      saveClientState: async () => { saves += 1; return true },
+      clearClientState: () => clear.promise,
+    })
+    const clearing = state.clearRestoredClientState()
+    state.updateRestorableSession(session("transient"))
+    await Promise.resolve(); clear.resolve(true); await clearing; await state.flushClientState()
+    assert.equal(state.loadedRestorableSession(), null)
+    assert.equal(saves, 0)
+  })
+})
+describe("flush behavior", () => {
+  it("waits for replacement writes, retries once, and bounds persistent failures", async () => {
+    let phase: "race" | "one-time" | "persistent" = "race", attempts = 0
+    const starts = [deferred<void>(), deferred<void>()], saves = [deferred<void>(), deferred<void>()]
+    const state = await boot({
+      loadClientState: async () => loadResult(),
+      saveClientState: async () => {
+        attempts += 1
+        if (phase === "race") { starts[attempts - 1]!.resolve(); await saves[attempts - 1]!.promise; return true }
+        if (phase === "persistent" || attempts === 1) throw new Error(`${phase} save failure`)
+        return true
+      },
+    })
+    state.updateRestorableSession(session("first"))
+    let settled = false
+    const flush = state.flushClientState().finally(() => { settled = true })
+    await starts[0]!.promise; state.updateRestorableSession(session("second"))
+    await new Promise((resolve) => setTimeout(resolve, 300)); saves[0]!.resolve(); await starts[1]!.promise
+    await Promise.resolve(); assert.equal(settled, false, "replacement save remains part of flush")
+    saves[1]!.resolve(); await flush
+    for (const test of [
+      { phase: "one-time" as const, attempts: 2, error: null },
+      { phase: "persistent" as const, attempts: 3, error: /persistent save failure/ },
+    ]) {
+      phase = test.phase; attempts = 0; state.updateRestorableSession(session(test.phase))
+      if (test.error) await assert.rejects(state.flushClientState(), test.error)
+      else await state.flushClientState()
+      assert.equal(attempts, test.attempts, test.phase)
+    }
+  })
+})
+describe("secondary hosts", () => {
+  for (const host of ["electron secondary", "plain web"] as const) {
+    it(`${host}: keeps layout local without restoring or writing snapshots`, async () => {
+      const storage = new MemoryStorage(); storage.setItem(layoutKey, "360")
+      let saves = 0
+      if (host === "plain web") {
+        storage.setItem("codenomad-client-snapshot-v1", JSON.stringify(snapshot("private")))
+        storage.setItem("codenomad-client-restore-enabled-v1", "false")
+      } else storage.removeItem(layoutKey)
+      const state = await boot(host === "plain web" ? undefined : {
+        loadClientState: async () => loadResult(snapshot("docs", { [layoutKey]: "380" }), false),
+        saveClientState: async () => { saves += 1; return false },
+      }, storage)
+      assert.equal(state.clientStateIsPrimary(), false)
+      assert.equal(state.loadedRestorableSession(), null)
+      assert.equal(state.readClientLayoutValue(layoutKey), host === "plain web" ? "360" : null)
+      state.writeClientLayoutValue(layoutKey, "420"); state.updateRestorableSession(session("other"))
+      await state.flushClientState()
+      assert.equal(storage.getItem(layoutKey), "420")
+      assert.equal(saves, 0)
+      if (host === "plain web") {
+        assert.equal(storage.getItem("codenomad-client-snapshot-v1"), null)
+        assert.equal(storage.getItem("codenomad-client-restore-enabled-v1"), null)
+      }
+    })
+  }
+})
diff --git a/packages/ui/src/stores/client-state.ts b/packages/ui/src/stores/client-state.ts
new file mode 100644
index 00000000..b13376e9
--- /dev/null
+++ b/packages/ui/src/stores/client-state.ts
@@ -0,0 +1,287 @@
+import { createSignal } from "solid-js"
+import { clearNativeClientState, loadNativeClientState, saveNativeClientState, setNativeRestoreEnabled } from "../lib/native/client-state"
+import { decodeClientSnapshot, isFutureClientSnapshot, normalizeRestorableSession } from "./client-state-codec"
+import type { ClientSnapshotV1, RestorableSessionState, RestorableSidecarTabState, RestorableTabState, RestorableWorkspaceTabState } from "./client-state-codec"
+export type { ClientSnapshotV1, RestorableSessionState, RestorableSidecarTabState, RestorableTabState, RestorableWorkspaceTabState }
+const SAVE_DEBOUNCE_MS = 250
+const FLUSH_MAX_ATTEMPTS = 3
+const MAX_LAYOUT_ENTRIES = 64
+const MAX_LAYOUT_KEY_LENGTH = 256
+const MAX_LAYOUT_VALUE_LENGTH = 4096
+const LEGACY_LAYOUT_KEY_PREFIX = "opencode-session-"
+const UNSAFE_LAYOUT_KEYS = new Set(["__proto__", "constructor", "prototype"])
+const [clientStateIsPrimary, setClientStateIsPrimary] = createSignal(true)
+const [restorePreviousStateEnabled, setRestorePreviousStateEnabledSignal] = createSignal(false)
+const [loadedClientSnapshotExists, setLoadedClientSnapshotExists] = createSignal(false)
+const [loadedRestorableSession, setLoadedRestorableSession] = createSignal<RestorableSessionState | null>(null)
+let initialized = false
+let initialization: Promise<void> | null = null
+let layout: Record<string, string> = Object.create(null)
+let revision = 0
+let dirty = false
+let writeBlock: false | "snapshot" | "transaction" = false
+let saveTimer: ReturnType<typeof setTimeout> | null = null
+let writeQueue: Promise<void> = Promise.resolve()
+let destructiveQueue: Promise<void> = Promise.resolve()
+let lastSaveError: unknown
+const transactionLayoutWrites = new Set<string>()
+function useLocalStorage<T>(fallback: T, operation: (storage: Storage) => T): T {
+  try {
+    return operation(window.localStorage)
+  } catch {
+    return fallback
+  }
+}
+
+function isValidLayoutKey(key: string): boolean {
+  return key.length > 0 && key.length <= MAX_LAYOUT_KEY_LENGTH && !UNSAFE_LAYOUT_KEYS.has(key)
+}
+const readLegacyLayoutValue = (key: string) =>
+  useLocalStorage<string | null>(null, (storage) => {
+    const value = storage.getItem(key)
+    return value !== null && value.length <= MAX_LAYOUT_VALUE_LENGTH ? value : null
+  })
+const writeLegacyLayoutValue = (key: string, value: string) =>
+  useLocalStorage(undefined, (storage) => storage.setItem(key, value))
+function legacyLayoutKeys(storage: Storage): string[] {
+  const keys = new Set(Object.keys(layout))
+  for (let index = 0; index < storage.length; index += 1) {
+    const key = storage.key(index)
+    if (key?.startsWith(LEGACY_LAYOUT_KEY_PREFIX)) keys.add(key)
+  }
+  return [...keys]
+}
+const hasLayoutKey = (key: string) => Object.prototype.hasOwnProperty.call(layout, key)
+const layoutIsFull = () => Object.keys(layout).length >= MAX_LAYOUT_ENTRIES
+
+function migrateLegacyLayoutValues(): boolean {
+  return useLocalStorage(false, (storage) => {
+    const previousSize = Object.keys(layout).length
+    for (const key of legacyLayoutKeys(storage)) {
+      if (hasLayoutKey(key)) continue
+      if (layoutIsFull()) break
+      const value = storage.getItem(key)
+      if (value === null || value.length > MAX_LAYOUT_VALUE_LENGTH) continue
+      layout[key] = value
+    }
+    return Object.keys(layout).length !== previousSize
+  })
+}
+
+function canWriteSnapshot(): boolean {
+  return initialized && clientStateIsPrimary() && restorePreviousStateEnabled() && !writeBlock
+}
+const cancelSaveTimer = () => {
+  if (saveTimer !== null) clearTimeout(saveTimer)
+  saveTimer = null
+}
+
+function enqueuePendingSave(): Promise<void> {
+  cancelSaveTimer()
+  if (!dirty || !canWriteSnapshot()) return writeQueue
+  const snapshot: ClientSnapshotV1 = {
+    version: 1,
+    revision: ++revision,
+    savedAt: Date.now(),
+    layout: { ...layout },
+    session: loadedRestorableSession(),
+  }
+  const normalizedSnapshot = decodeClientSnapshot(snapshot)
+  if (!normalizedSnapshot) return Promise.reject(new Error("Client snapshot normalization failed"))
+  layout = { ...normalizedSnapshot.layout }
+  dirty = false
+  const saveAttempt = writeQueue.then(async () => {
+    try {
+      if (!await saveNativeClientState(normalizedSnapshot)) {
+        setClientStateIsPrimary(false)
+        throw new Error("Native client state save was rejected")
+      }
+      lastSaveError = undefined
+    } catch (error) {
+      dirty = true
+      lastSaveError = error
+      throw error
+    }
+  })
+  writeQueue = saveAttempt.catch(() => undefined)
+  return saveAttempt
+}
+
+function scheduleSave() {
+  dirty = true
+  if (!canWriteSnapshot()) return
+  cancelSaveTimer()
+  saveTimer = setTimeout(() => void enqueuePendingSave()
+    .catch((error) => console.warn("[client-state] failed to save client snapshot", error)), SAVE_DEBOUNCE_MS)
+}
+function resetLoadedState(snapshot: ClientSnapshotV1 | null = null, resetRevision = false) {
+  layout = snapshot ? { ...snapshot.layout } : Object.create(null)
+  if (resetRevision) revision = snapshot?.revision ?? 0
+  setLoadedClientSnapshotExists(snapshot !== null)
+  setLoadedRestorableSession(snapshot?.session ?? null)
+}
+async function executeDestructiveTransaction(operation: () => Promise<boolean>, rejectedMessage: string, loseOwnershipOnRejection = false): Promise<void> {
+  const previousWriteBlock = writeBlock
+  let retryDirty = dirty
+  writeBlock = "transaction"
+  transactionLayoutWrites.clear()
+  cancelSaveTimer()
+  dirty = false
+  try {
+    await writeQueue
+    retryDirty ||= dirty
+    dirty = false
+    if (!await operation()) {
+      if (loseOwnershipOnRejection) setClientStateIsPrimary(false)
+      throw new Error(rejectedMessage)
+    }
+    useLocalStorage(undefined, (storage) => {
+      for (const key of legacyLayoutKeys(storage)) storage.removeItem(key)
+    })
+    resetLoadedState()
+    transactionLayoutWrites.clear()
+    writeBlock = "snapshot"
+  } catch (error) {
+    retryDirty ||= dirty
+    for (const key of transactionLayoutWrites) writeLegacyLayoutValue(key, layout[key]!)
+    transactionLayoutWrites.clear()
+    writeBlock = previousWriteBlock
+    dirty = retryDirty
+    if (dirty) scheduleSave()
+    throw error
+  }
+}
+function runDestructiveTransition(operation: () => Promise<void>): Promise<void> {
+  const transition = destructiveQueue.then(operation)
+  destructiveQueue = transition.catch(() => undefined)
+  return transition
+}
+export function updateRestorableSession(state: RestorableSessionState | null): void {
+  const normalized = state === null ? null : normalizeRestorableSession(state)
+  if (state !== null && normalized === null) return
+  if (writeBlock === "transaction") {
+    setLoadedRestorableSession(normalized)
+    dirty = true
+    return
+  }
+  if (writeBlock || !clientStateIsPrimary() || !restorePreviousStateEnabled()) return
+  setLoadedRestorableSession(normalized)
+  scheduleSave()
+}
+
+export function readClientLayoutValue(key: string): string | null {
+  if (!isValidLayoutKey(key)) return null
+  if (!clientStateIsPrimary()) return readLegacyLayoutValue(key)
+  if (!restorePreviousStateEnabled() || writeBlock) return null
+  if (hasLayoutKey(key)) return layout[key] ?? null
+  const legacyValue = readLegacyLayoutValue(key)
+  if (legacyValue === null || layoutIsFull()) return legacyValue
+  layout[key] = legacyValue
+  scheduleSave()
+  return legacyValue
+}
+
+export function writeClientLayoutValue(key: string, value: string): void {
+  if (!isValidLayoutKey(key) || value.length > MAX_LAYOUT_VALUE_LENGTH) return
+  if (!clientStateIsPrimary()) return writeLegacyLayoutValue(key, value)
+  if (writeBlock === "transaction") {
+    if (!hasLayoutKey(key) && layoutIsFull()) return
+    dirty ||= layout[key] !== value
+    layout[key] = value
+    transactionLayoutWrites.add(key)
+    return
+  }
+  if (!restorePreviousStateEnabled() || writeBlock) return
+  if (!hasLayoutKey(key) && layoutIsFull()) return
+  writeLegacyLayoutValue(key, value)
+  if (layout[key] === value) return
+  layout[key] = value
+  scheduleSave()
+}
+
+export async function flushClientState(): Promise<void> {
+  cancelSaveTimer()
+  let lastError = lastSaveError
+  for (let attempts = 0; attempts < FLUSH_MAX_ATTEMPTS; attempts += 1) {
+    while (true) {
+      const pending = writeQueue
+      await pending
+      if (pending === writeQueue) break
+    }
+    if (!dirty) {
+      if (lastError !== undefined) throw lastError
+      return
+    }
+    if (!canWriteSnapshot()) {
+      const writeError = lastSaveError ?? lastError
+      if (writeError !== undefined) throw writeError
+      return
+    }
+    try {
+      await enqueuePendingSave()
+      lastError = undefined
+    } catch (error) {
+      lastError = error
+    }
+  }
+  await writeQueue
+  if (!dirty) return
+  throw lastError ?? new Error("Client state remained dirty after the final flush attempt")
+}
+
+export async function clearRestoredClientState(): Promise<void> {
+  await runDestructiveTransition(async () => {
+    if (!clientStateIsPrimary()) throw new Error("Client state is not owned by this window")
+    await executeDestructiveTransaction(clearNativeClientState, "Native client state clear was rejected", true)
+  })
+}
+
+export async function setRestorePreviousStateEnabled(enabled: boolean): Promise<void> {
+  await runDestructiveTransition(async () => {
+    if (enabled === restorePreviousStateEnabled() && (!enabled || writeBlock === false)) return
+    if (!clientStateIsPrimary()) throw new Error("Client state is not owned by this window")
+    if (enabled) {
+      if (!await setNativeRestoreEnabled(true)) throw new Error("Native restore preference update was rejected")
+      writeBlock = false
+      setRestorePreviousStateEnabledSignal(true)
+      return
+    }
+    setRestorePreviousStateEnabledSignal(false)
+    try {
+      await executeDestructiveTransaction(() => setNativeRestoreEnabled(false), "Native restore preference update was rejected")
+    } catch (error) {
+      setRestorePreviousStateEnabledSignal(true)
+      throw error
+    }
+  })
+}
+
+export function initializeClientState(): Promise<void> {
+  if (initialization) return initialization
+  initialization = (async () => {
+    try {
+      const loaded = await loadNativeClientState()
+      setClientStateIsPrimary(loaded.isPrimary)
+      setRestorePreviousStateEnabledSignal(loaded.restoreEnabled)
+      resetLoadedState(null, true)
+      dirty = false
+      lastSaveError = undefined
+      writeBlock = false
+      transactionLayoutWrites.clear()
+      initialized = true
+      if (!loaded.isPrimary || !loaded.restoreEnabled) return
+      writeBlock = isFutureClientSnapshot(loaded.snapshot) ? "snapshot" : false
+      const snapshot = decodeClientSnapshot(loaded.snapshot)
+      resetLoadedState(snapshot, true)
+      if (!writeBlock && migrateLegacyLayoutValues()) scheduleSave()
+    } catch (error) {
+      initialized = true
+      setClientStateIsPrimary(false)
+      resetLoadedState()
+      console.warn("[client-state] failed to initialize client state", error)
+    }
+  })()
+  return initialization
+}
+
+export { clientStateIsPrimary, loadedClientSnapshotExists, loadedRestorableSession, restorePreviousStateEnabled }
diff --git a/packages/ui/src/stores/commands.ts b/packages/ui/src/stores/commands.ts
index ac60efca..a9f0ed3c 100644
--- a/packages/ui/src/stores/commands.ts
+++ b/packages/ui/src/stores/commands.ts
@@ -26,5 +26,3 @@ export function clearCommands(instanceId: string): void {
     return next
   })
 }
-
-export { commandMap as commands }
diff --git a/packages/ui/src/stores/conversation-speech.ts b/packages/ui/src/stores/conversation-speech.ts
index 34a76784..38bc277f 100644
--- a/packages/ui/src/stores/conversation-speech.ts
+++ b/packages/ui/src/stores/conversation-speech.ts
@@ -100,7 +100,7 @@ export function isConversationModeEnabled(instanceId: string): boolean {
 
 export function canUseConversationMode(): boolean {
   const capabilities = speechCapabilities()
-  if (!capabilities?.available || !capabilities.configured || !capabilities.supportsTts) {
+  if (!capabilities?.available || !capabilities.ttsConfigured || !capabilities.supportsTts) {
     return false
   }
 
@@ -291,7 +291,7 @@ async function createPlaybackHandle(text: string): Promise<PlaybackHandle> {
   const capabilities = (await loadSpeechCapabilities()) ?? speechCapabilities()
   const settings = serverSettings().speech
 
-  if (!capabilities?.available || !capabilities.configured || !capabilities.supportsTts) {
+  if (!capabilities?.available || !capabilities.ttsConfigured || !capabilities.supportsTts) {
     throw new Error(tGlobal("messageItem.actions.speak.error.unavailable"))
   }
 
diff --git a/packages/ui/src/stores/instance-lifecycle-authority.ts b/packages/ui/src/stores/instance-lifecycle-authority.ts
new file mode 100644
index 00000000..c939ec08
--- /dev/null
+++ b/packages/ui/src/stores/instance-lifecycle-authority.ts
@@ -0,0 +1,19 @@
+export interface InstanceLifecycleAuthorityEvent {
+  type: "removed" | "opened" | "unavailable"
+  instanceId: string
+  folder: string
+  occurrence: number
+}
+
+const listeners = new Set<(event: InstanceLifecycleAuthorityEvent) => void>()
+
+export function onInstanceLifecycleAuthority(
+  listener: (event: InstanceLifecycleAuthorityEvent) => void,
+): () => void {
+  listeners.add(listener)
+  return () => listeners.delete(listener)
+}
+
+export function publishInstanceLifecycleAuthority(event: InstanceLifecycleAuthorityEvent): void {
+  for (const listener of listeners) listener(event)
+}
diff --git a/packages/ui/src/stores/instance-runtime-authority.test.ts b/packages/ui/src/stores/instance-runtime-authority.test.ts
new file mode 100644
index 00000000..98a330c9
--- /dev/null
+++ b/packages/ui/src/stores/instance-runtime-authority.test.ts
@@ -0,0 +1,222 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { createFileAttachment, createTextAttachment } from "../types/attachment.ts"
+import {
+  addAttachment, clearInstanceAttachments, getAttachments, hydrateSessionAttachments, removeAttachment,
+  getAuthoritativeAttachmentSessionIdsForInstance,
+} from "./attachments.ts"
+import { addInstance, clearReloadableInstanceState, removeInstance } from "./instances.ts"
+import {
+  activeParentSessionId, activeSessionId, clearActiveParentSession, clearInstanceDraftPromptValues,
+  clearInstanceDraftPrompts, clearInstanceDeletedSessionAuthority, clearInstanceSessionSelection,
+  clearSessionDraftPrompt, getAuthoritativeDraftSessionIdsForInstance,
+  getAuthoritativelyDeletedSessionIdsForInstance, getSessionDraftPromptsForInstance,
+  hasAuthoritativeSessionSelection, hydrateActiveSessionSelection, hydrateSessionDraftPrompt,
+  setActiveParentSession, setActiveSession, setSessions, setSessionDraftPrompt,
+} from "./session-state.ts"
+import { removeSessionRuntimeState } from "./session-api.ts"
+import { handleSessionDeleted } from "./session-events.ts"
+import {
+  createRestorableSessionPreservation, markPreservedWorkspaceRemoved, markPreservedWorkspaceReopened,
+  mergeRestorableSessionState, recordRestoredTab,
+} from "./app-session-snapshot-merge.ts"
+import type { RestorableWorkspaceTabState } from "./client-state-codec.ts"
+import { onInstanceLifecycleAuthority } from "./instance-lifecycle-authority.ts"
+
+const absent = { tabs: [], activeTabIndex: -1 }
+function workspace(state: Partial<RestorableWorkspaceTabState> = {}): RestorableWorkspaceTabState {
+  return { kind: "workspace", folder: "/work", occurrence: 0, drafts: {}, attachments: {},
+    scrollSnapshots: {}, unseenIdleSince: {}, generationRecovery: {}, ...state }
+}
+function instance(id: string, folder = "/work", status: "ready" | "error" = "ready") {
+  return { id, folder, port: 0, pid: 0, proxyPath: "", status, client: null }
+}
+function clearSessionState(instanceId: string) {
+  clearInstanceAttachments(instanceId)
+  clearInstanceDraftPrompts(instanceId)
+  clearInstanceDeletedSessionAuthority(instanceId)
+  clearInstanceSessionSelection(instanceId)
+  setSessions((previous) => { const next = new Map(previous); next.delete(instanceId); return next })
+}
+function selectParentAndChild(instanceId: string) {
+  const parent = { id: "parent", instanceId, parentId: null, title: "Parent", status: "idle" }
+  const child = { id: "child", instanceId, parentId: "parent", title: "Child", status: "idle" }
+  setSessions((previous) => new Map(previous).set(instanceId, new Map<string, any>([["parent", parent], ["child", child]])))
+  setActiveParentSession(instanceId, "parent")
+  setActiveSession(instanceId, "child")
+}
+function preservationHarness(tabs: RestorableWorkspaceTabState[]) {
+  let value = createRestorableSessionPreservation({ tabs, activeTabIndex: 0 })
+  const stop = onInstanceLifecycleAuthority((event) => {
+    const descriptor = { runtimeTabId: `instance:${event.instanceId}`, folder: event.folder, occurrence: event.occurrence }
+    value = event.type === "removed"
+      ? markPreservedWorkspaceRemoved(value, descriptor)
+      : markPreservedWorkspaceReopened(value, descriptor)
+  })
+  return {
+    get value() { return value },
+    map(sourceIndex: number, instanceId: string, unavailable?: ReadonlySet<string>) {
+      recordRestoredTab(value, sourceIndex, `instance:${instanceId}`, unavailable)
+    },
+    close() { stop() },
+  }
+}
+
+describe("instance runtime authority", () => {
+  it("preserves pasted and file attachments with prompt content during rehydration cleanup", () => {
+    const id = "rehydrate-unsent-attachments", sessionId = "draft-session"
+    const pasted = createTextAttachment("pasted body", "pasted #1 (4 lines)", "paste-1.txt")
+    const file = createFileAttachment("/work/notes.txt", "notes.txt", "text/plain", new TextEncoder().encode("notes"))
+    addAttachment(id, sessionId, pasted); addAttachment(id, sessionId, file)
+    setSessionDraftPrompt(id, sessionId, "Review [pasted #1] and @notes.txt")
+    clearReloadableInstanceState(id)
+    assert.equal(getSessionDraftPromptsForInstance(id)[sessionId], "Review [pasted #1] and @notes.txt")
+    assert.deepEqual(getAttachments(id, sessionId), [pasted, file])
+    clearSessionState(id)
+  })
+
+  for (const test of [
+    { label: "direct definitive session removal", remove: removeSessionRuntimeState },
+    { label: "session.deleted event", remove: (id: string, sessionId: string) => handleSessionDeleted(id,
+      { type: "session.deleted", properties: { info: { id: sessionId } } }) },
+  ]) it(`removes attachment authority on ${test.label}`, () => {
+    const id = `authority-${test.label}`, sessionId = "deleted-session"
+    addAttachment(id, sessionId, createTextAttachment("pasted", "pasted #1", "paste.txt"))
+    setSessionDraftPrompt(id, sessionId, "[pasted #1]")
+    test.remove(id, sessionId)
+    assert.deepEqual(getAttachments(id, sessionId), [])
+    assert.equal(getAuthoritativeAttachmentSessionIdsForInstance(id).has(sessionId), false)
+    assert.equal(getSessionDraftPromptsForInstance(id)[sessionId], undefined)
+    assert.equal(getAuthoritativelyDeletedSessionIdsForInstance(id).has(sessionId), true)
+    clearSessionState(id)
+  })
+
+  for (const test of [
+    { label: "retained parent when active child is deleted", deleted: "child", parent: "parent", active: "parent" },
+    { label: "no selection when selected parent is deleted", deleted: "parent", parent: undefined, active: undefined },
+  ] as const) it(`selects ${test.label}`, () => {
+    const id = `selection-${test.deleted}`
+    selectParentAndChild(id)
+    removeSessionRuntimeState(id, test.deleted)
+    assert.equal(activeParentSessionId().get(id), test.parent)
+    assert.equal(activeSessionId().get(id), test.active)
+    clearSessionState(id)
+  })
+
+  it("tombstones failed hydration only after removal and reopens it as pending", () => {
+    const id = "failed-hydration-removal"
+    const harness = preservationHarness([workspace({ folder: "/failed", drafts: { missing: "retry me" } })])
+    addInstance(instance(id, "/failed", "error")); harness.map(0, id)
+    try {
+      assert.equal(mergeRestorableSessionState(absent, harness.value).tabs.length, 1)
+      removeInstance(id)
+      assert.equal(mergeRestorableSessionState(absent, harness.value).tabs.length, 0)
+      assert.equal(harness.value.results[0]?.status, "removed")
+      addInstance(instance(`${id}-reopened`, "/failed"))
+      assert.equal(mergeRestorableSessionState(absent, harness.value).tabs.length, 1)
+      assert.equal(harness.value.results[0]?.status, "pending")
+    } finally {
+      harness.close(); removeInstance(id, { authoritative: false }); removeInstance(`${id}-reopened`, { authoritative: false })
+    }
+  })
+
+  it("keeps a pending source tab after non-authoritative startup removal", () => {
+    const id = "automatic-startup-removal"
+    const harness = preservationHarness([workspace({ folder: "/automatic", drafts: { missing: "retry me" } })])
+    addInstance(instance(id, "/automatic", "error")); harness.map(0, id)
+    try {
+      removeInstance(id, { authoritative: false })
+      assert.equal(harness.value.results[0]?.status, "pending")
+      assert.equal(mergeRestorableSessionState(absent, harness.value).tabs.length, 1)
+    } finally {
+      harness.close(); removeInstance(id, { authoritative: false })
+    }
+  })
+
+  it("tombstones each mapped failed-hydration duplicate after sequential closes", () => {
+    const ids = ["duplicate-first", "duplicate-second"]
+    const harness = preservationHarness(ids.map((id, occurrence) =>
+      workspace({ folder: "/duplicate", occurrence, drafts: { [id]: `retry ${id}` } })))
+    ids.forEach((id, index) => { addInstance(instance(id, "/duplicate", "error")); harness.map(index, id) })
+    try {
+      ids.forEach((id) => removeInstance(id))
+      assert.deepEqual(mergeRestorableSessionState(absent, harness.value), absent)
+      assert.deepEqual(harness.value.results.map(({ status }) => status), ["removed", "removed"])
+    } finally { harness.close(); ids.forEach((id) => removeInstance(id, { authoritative: false })) }
+  })
+
+  for (const closeOrder of [["middle", "last"], ["last", "middle"]] as const) {
+    it(`keeps source zero across occurrence renumbering when closing ${closeOrder.join(" then ")}`, () => {
+      const ids = { first: `three-first-${closeOrder[0]}`, middle: `three-middle-${closeOrder[0]}`, last: `three-last-${closeOrder[0]}` }
+      const harness = preservationHarness([
+        workspace({ folder: "/three", occurrence: 0, drafts: { first: "keep open" } }),
+        workspace({ folder: "/three", occurrence: 1, drafts: { middle: "close middle" } }),
+        workspace({ folder: "/three", occurrence: 2, drafts: { last: "close last" } }),
+      ])
+      Object.values(ids).forEach((id, index) => { addInstance(instance(id, "/three", "error")); harness.map(index, id) })
+      try {
+        closeOrder.forEach((position) => removeInstance(ids[position]))
+        assert.deepEqual(harness.value.results.flatMap((result, index) => result.status === "removed" ? [index] : []), [1, 2])
+        const merged = mergeRestorableSessionState(
+          { tabs: [workspace({ folder: "/three" })], activeTabIndex: 0 }, harness.value,
+          { currentTabIds: [`instance:${ids.first}`] },
+        )
+        const drafts = merged.tabs[0]?.kind === "workspace" ? merged.tabs[0].drafts : {}
+        assert.deepEqual(drafts, { first: "keep open" })
+      } finally { harness.close(); Object.values(ids).forEach((id) => removeInstance(id, { authoritative: false })) }
+    })
+  }
+
+  it("retains an explicit draft-clear tombstone through rehydrate value cleanup", () => {
+    const id = "draft-rehydrate-authority", sessionId = "missing-session"
+    const preserved = createRestorableSessionPreservation({
+      tabs: [workspace({ drafts: { [sessionId]: "preserved draft" } })], activeTabIndex: 0,
+    })
+    hydrateSessionDraftPrompt(id, sessionId, "restored draft"); clearSessionDraftPrompt(id, sessionId); clearInstanceDraftPromptValues(id)
+    const authority = getAuthoritativeDraftSessionIdsForInstance(id)
+    assert.equal(authority.has(sessionId), true)
+    assert.deepEqual(getSessionDraftPromptsForInstance(id), {})
+    const merged = mergeRestorableSessionState({ tabs: [workspace()], activeTabIndex: 0 }, preserved,
+      { currentTabIds: [`instance:${id}`], currentTabAuthorities: [{ drafts: authority }] })
+    assert.deepEqual(merged.tabs[0]?.kind === "workspace" ? merged.tabs[0].drafts : undefined, {})
+    clearInstanceDraftPrompts(id)
+    assert.equal(getAuthoritativeDraftSessionIdsForInstance(id).has(sessionId), false)
+  })
+
+  it("keeps an explicitly closed selection at none and clears authority on final removal", () => {
+    const id = "selection-close-authority"
+    addInstance(instance(id))
+    const preserved = createRestorableSessionPreservation({ tabs: [workspace({
+      activeParentSessionId: "missing-parent", activeSessionId: "missing-child",
+    })], activeTabIndex: 0 })
+    recordRestoredTab(preserved, 0, `instance:${id}`, new Set(["missing-parent", "missing-child"]))
+    hydrateActiveSessionSelection(id, null, null)
+    assert.equal(hasAuthoritativeSessionSelection(id), false)
+    setActiveParentSession(id, "current-session"); clearActiveParentSession(id)
+    hydrateActiveSessionSelection(id, "missing-parent", "missing-child")
+    assert.equal(activeParentSessionId().has(id), false); assert.equal(activeSessionId().has(id), false)
+    assert.equal(hasAuthoritativeSessionSelection(id), true)
+    const merged = mergeRestorableSessionState({ tabs: [workspace()], activeTabIndex: 0 }, preserved,
+      { currentTabIds: [`instance:${id}`], currentTabAuthorities: [{ sessionSelection: true }] })
+    const tab = merged.tabs[0]
+    assert.equal(tab?.kind === "workspace" ? tab.activeParentSessionId : undefined, undefined)
+    assert.equal(tab?.kind === "workspace" ? tab.activeSessionId : undefined, undefined)
+    clearSessionDraftPrompt(id, "removed-session")
+    const attachment = createTextAttachment("removed", "pasted #1", "removed.txt")
+    hydrateSessionAttachments(id, "removed-session", [attachment]); removeAttachment(id, "removed-session", attachment.id)
+    removeInstance(id)
+    assert.equal(hasAuthoritativeSessionSelection(id), false)
+    assert.equal(getAuthoritativeDraftSessionIdsForInstance(id).size, 0)
+    assert.equal(getAuthoritativeAttachmentSessionIdsForInstance(id).size, 0)
+  })
+
+  it("marks info selection as authoritative without restore hydration doing so", () => {
+    const id = "info-selection-authority"
+    hydrateActiveSessionSelection(id, null, "info")
+    assert.equal(hasAuthoritativeSessionSelection(id), false)
+    setActiveSession(id, "info")
+    assert.equal(hasAuthoritativeSessionSelection(id), true)
+    clearInstanceSessionSelection(id)
+  })
+})
diff --git a/packages/ui/src/stores/instances-restore-cancellation.test.ts b/packages/ui/src/stores/instances-restore-cancellation.test.ts
new file mode 100644
index 00000000..149c8503
--- /dev/null
+++ b/packages/ui/src/stores/instances-restore-cancellation.test.ts
@@ -0,0 +1,20 @@
+import assert from "node:assert/strict"
+import { it } from "node:test"
+
+import { serverApi } from "../lib/api-client.ts"
+import { cancelRestoreCreation } from "./restore-creation-cancellation.ts"
+
+it("retries pre-response restore cancellation without SSE correlation", async () => {
+  const originalCancel = serverApi.cancelWorkspaceCreation
+  let calls = 0
+  serverApi.cancelWorkspaceCreation = async () => {
+    if (++calls === 1) throw new Error("temporary cancellation failure")
+  }
+
+  try {
+    await cancelRestoreCreation("pre-response-request")
+    assert.equal(calls, 2)
+  } finally {
+    serverApi.cancelWorkspaceCreation = originalCancel
+  }
+})
diff --git a/packages/ui/src/stores/instances-restore-ownership.test.ts b/packages/ui/src/stores/instances-restore-ownership.test.ts
new file mode 100644
index 00000000..e6a151cc
--- /dev/null
+++ b/packages/ui/src/stores/instances-restore-ownership.test.ts
@@ -0,0 +1,47 @@
+import assert from "node:assert/strict"
+import { it } from "node:test"
+
+import { serverApi } from "../lib/api-client.ts"
+import { AbortCreatedWorkspaceCleanup } from "./abort-created-workspace-cleanup.ts"
+import {
+  createInstance, releaseRestoreCreatedInstance, removeInstance,
+} from "./instances.ts"
+
+it("only restore-scoped creations are owned by abort cleanup", async () => {
+  const originalCreate = serverApi.createWorkspace
+  const originalRelease = serverApi.releaseWorkspaceCreation
+  const originalTrack = AbortCreatedWorkspaceCleanup.prototype.track
+  const tracked: Array<{ id: string; requestId?: string }> = []
+  const released: Array<[string, string]> = []
+
+  serverApi.createWorkspace = async (payload) => ({
+    id: payload.path.slice(1), requestId: payload.requestId, path: payload.path, status: "starting",
+    proxyPath: "", binaryId: "test", binaryLabel: "Test", createdAt: "", updatedAt: "",
+  })
+  serverApi.releaseWorkspaceCreation = async (id, requestId) => { released.push([id, requestId]) }
+  AbortCreatedWorkspaceCleanup.prototype.track = function (workspace) {
+    tracked.push(workspace)
+    originalTrack.call(this, workspace)
+  }
+
+  try {
+    await createInstance("/ordinary", undefined, undefined, { activate: false })
+    assert.equal(tracked.some(({ id }) => id === "ordinary"), false)
+
+    const restored = await createInstance("/restore", undefined, undefined, {
+      activate: false,
+      signal: new AbortController().signal,
+    })
+    assert.ok(restored.requestId)
+    assert.equal(tracked.some(({ id, requestId }) => id === "restore" && requestId === restored.requestId), true)
+    await releaseRestoreCreatedInstance("restore", restored.requestId)
+    await releaseRestoreCreatedInstance("restore", restored.requestId)
+    assert.deepEqual(released, [["restore", restored.requestId]])
+  } finally {
+    AbortCreatedWorkspaceCleanup.prototype.track = originalTrack
+    serverApi.createWorkspace = originalCreate
+    serverApi.releaseWorkspaceCreation = originalRelease
+    removeInstance("ordinary", { authoritative: false })
+    removeInstance("restore", { authoritative: false })
+  }
+})
diff --git a/packages/ui/src/stores/instances.ts b/packages/ui/src/stores/instances.ts
index 96fddf6d..04a40f3d 100644
--- a/packages/ui/src/stores/instances.ts
+++ b/packages/ui/src/stores/instances.ts
@@ -17,6 +17,10 @@ import {
   fetchAgents,
   fetchProviders,
   clearInstanceDraftPrompts,
+  clearSessionListRequestState,
+  clearInstanceDeletedSessionAuthority,
+  clearInstanceSessionExpansionState,
+  clearInstanceSessionSelection,
   resetSessionPagination,
 } from "./sessions"
 import {
@@ -30,7 +34,12 @@ import { getRootClient } from "./opencode-client"
 import { clearOpenCodeWorkspaceCache, getOpenCodeWorkspaceIdForSession, getOpenCodeWorkspaceIdForWorktree, syncOpenCodeWorkspaces } from "./opencode-workspaces"
 import { fetchCommands, clearCommands } from "./commands"
 import { serverSettings } from "./preferences"
-import { sessions, setSessionPendingPermission, setSessionPendingQuestion } from "./session-state"
+import {
+  reconcileSessionPendingState,
+  sessions,
+  setSessionPendingPermission,
+  setSessionPendingQuestion,
+} from "./session-state"
 import { setHasInstances } from "./ui"
 import { messageStoreBus } from "./message-v2/bus"
 import { upsertPermissionV2, removePermissionV2, upsertQuestionV2, removeQuestionV2 } from "./message-v2/bridge"
@@ -41,10 +50,10 @@ import {
   pruneRepliedPermissions,
 } from "./permission-replies"
 import {
-  clearAutoAcceptPermission,
-  drainAutoAcceptPermissions,
+  clearPermissionAutoAcceptForInstance,
   isPermissionAutoAcceptEnabled,
   resolvePermissionAutoAcceptFamilyRoot,
+  setPermissionAutoAcceptEnabled,
   setPermissionAutoAcceptFamilyRootResolver,
   togglePermissionAutoAccept,
 } from "./permission-auto-accept"
@@ -56,6 +65,19 @@ import { activeSidecarToken } from "./sidecars"
 import { buildV2RequestLocations, type V2Location } from "./request-locations"
 import { showToastNotification } from "../lib/notifications"
 import { tGlobal } from "../lib/i18n"
+import { appSessionRestoreGateActive } from "./app-session-restore-gate"
+import { clearInstanceAttachments } from "./attachments"
+import { publishInstanceLifecycleAuthority } from "./instance-lifecycle-authority"
+import { getUnavailableWorkspaceIds } from "./app-session-reconciliation"
+import { getAbortReason } from "./app-session-restore-timeout"
+import { AbortCreatedWorkspaceCleanup } from "./abort-created-workspace-cleanup"
+import { TrailingResyncCoordinator, waitForSettledPrerequisite } from "../lib/trailing-resync"
+import { retryWithBackoff } from "../lib/retry-utils"
+import { cancelRestoreCreation } from "./restore-creation-cancellation"
+import {
+  RestoreWorkspaceCommitGates, type RestoreWorkspaceCommitGate, type RestoreWorkspaceTerminal,
+} from "./restore-workspace-commit-gates"
+import { WorkspaceListReconciliationFence } from "./workspace-list-reconciliation-fence"
 
 const log = getLogger("api")
 
@@ -65,6 +87,31 @@ setPermissionAutoAcceptFamilyRootResolver((instanceId, sessionId) => {
   return resolvePermissionAutoAcceptFamilyRoot(sessionId, (id) => instanceSessions.get(id))
 })
 
+// Server is authoritative for Yolo state; mirror toggles (incl. from other
+// clients) arriving over the CodeNomad server event stream into the local
+// projection so the badge/switch stay in sync.
+serverEvents.on("yolo.stateChanged", (event) => {
+  if (event.type !== "yolo.stateChanged") return
+  const { instanceId, sessionId, enabled } = event
+  if (typeof instanceId !== "string" || typeof sessionId !== "string" || typeof enabled !== "boolean") return
+  log.info(`[SSE] Yolo state changed: ${instanceId}:${sessionId} -> ${enabled}`)
+  setPermissionAutoAcceptEnabled(instanceId, sessionId, enabled)
+})
+
+// When the server auto-accepts a permission, clean up the UI queue immediately
+// instead of waiting for the OpenCode permission.replied SSE event (which may
+// be delayed or missed on a flaky connection). This preserves the #424
+// invariant: auto-accept cleanup happens at the queue level, not tied to
+// external event timing.
+serverEvents.on("yolo.autoAccepted", (event) => {
+  if (event.type !== "yolo.autoAccepted") return
+  const { instanceId, permissionId } = event
+  if (typeof instanceId !== "string" || typeof permissionId !== "string") return
+  markPermissionReplied(instanceId, permissionId)
+  removePermissionFromQueue(instanceId, permissionId)
+  removePermissionV2(instanceId, permissionId)
+})
+
 const [instances, setInstances] = createSignal<Map<string, Instance>>(new Map())
 
 const [activeInstanceId, setActiveInstanceId] = createSignal<string | null>(null)
@@ -74,75 +121,74 @@ const [logStreamingState, setLogStreamingState] = createSignal<Map<string, boole
 // Interruption queues (permissions + questions) per instance
 const [permissionQueues, setPermissionQueues] = createSignal<Map<string, PermissionRequest[]>>(new Map())
 const [activePermissionId, setActivePermissionId] = createSignal<Map<string, string | null>>(new Map())
-const permissionSessionCounts = new Map<string, Map<string, number>>()
-const permissionEnqueuedAt = new Map<string, number>()
-const permissionSourceByInstance = new Map<string, Map<string, PermissionSource>>()
 
 const [questionQueues, setQuestionQueues] = createSignal<Map<string, QuestionRequest[]>>(new Map())
 const [activeQuestionId, setActiveQuestionId] = createSignal<Map<string, string | null>>(new Map())
-const questionSessionCounts = new Map<string, Map<string, number>>()
-const questionEnqueuedAt = new Map<string, number>()
-const questionSourceByInstance = new Map<string, Map<string, QuestionSource>>()
+class InterruptionRegistry<T extends { id: string }, S extends string> {
+  private readonly enqueuedAt = new Map<string, number>()
+  private readonly sources = new Map<string, Map<string, S>>()
+  private readonly sessionCounts = new Map<string, Map<string, number>>()
 
-function ensurePermissionEnqueuedAt(permission: PermissionRequest): number {
-  const existing = permissionEnqueuedAt.get(permission.id)
-  if (existing) return existing
-  const now = Date.now()
-  permissionEnqueuedAt.set(permission.id, now)
-  return now
-}
+  constructor(private readonly defaultSource: S) {}
 
-function setPermissionSource(instanceId: string, requestId: string, source: PermissionSource): void {
-  let sources = permissionSourceByInstance.get(instanceId)
-  if (!sources) {
-    sources = new Map()
-    permissionSourceByInstance.set(instanceId, sources)
+  ensureEnqueuedAt(request: T): number {
+    const existing = this.enqueuedAt.get(request.id)
+    if (existing) return existing
+    const now = Date.now()
+    this.enqueuedAt.set(request.id, now)
+    return now
   }
-  sources.set(requestId, source)
-}
 
-function getPermissionSource(instanceId: string, requestId: string): PermissionSource {
-  return permissionSourceByInstance.get(instanceId)?.get(requestId) ?? "v2"
-}
+  enqueuedAtFor(requestId: string): number {
+    return this.enqueuedAt.get(requestId) ?? Date.now()
+  }
 
-function deletePermissionSource(instanceId: string, requestId: string): void {
-  const sources = permissionSourceByInstance.get(instanceId)
-  if (!sources) return
-  sources.delete(requestId)
-  if (sources.size === 0) {
-    permissionSourceByInstance.delete(instanceId)
+  setSource(instanceId: string, requestId: string, source: S): void {
+    const sources = this.sources.get(instanceId) ?? new Map<string, S>()
+    sources.set(requestId, source)
+    this.sources.set(instanceId, sources)
+  }
+
+  getSource(instanceId: string, requestId: string): S {
+    return this.sources.get(instanceId)?.get(requestId) ?? this.defaultSource
+  }
+
+  remove(instanceId: string, requestId: string): void {
+    this.enqueuedAt.delete(requestId)
+    const sources = this.sources.get(instanceId)
+    sources?.delete(requestId)
+    if (sources?.size === 0) this.sources.delete(instanceId)
+  }
+
+  increment(instanceId: string, sessionId: string): void {
+    const counts = this.sessionCounts.get(instanceId) ?? new Map<string, number>()
+    counts.set(sessionId, (counts.get(sessionId) ?? 0) + 1)
+    this.sessionCounts.set(instanceId, counts)
+  }
+
+  decrement(instanceId: string, sessionId: string): number {
+    const counts = this.sessionCounts.get(instanceId)
+    const next = Math.max(0, (counts?.get(sessionId) ?? 0) - 1)
+    if (next) counts?.set(sessionId, next)
+    else counts?.delete(sessionId)
+    if (counts?.size === 0) this.sessionCounts.delete(instanceId)
+    return next
+  }
+
+  sessionIds(instanceId: string): IterableIterator<string> {
+    return this.sessionCounts.get(instanceId)?.keys() ?? new Map<string, number>().keys()
+  }
+
+  clear(instanceId: string, requests: readonly T[], clearPending: (sessionId: string) => void): void {
+    requests.forEach(({ id }) => this.enqueuedAt.delete(id))
+    this.sources.delete(instanceId)
+    for (const sessionId of this.sessionCounts.get(instanceId)?.keys() ?? []) clearPending(sessionId)
+    this.sessionCounts.delete(instanceId)
   }
 }
 
-function ensureQuestionEnqueuedAt(request: QuestionRequest): number {
-  const existing = questionEnqueuedAt.get(request.id)
-  if (existing) return existing
-  const now = Date.now()
-  questionEnqueuedAt.set(request.id, now)
-  return now
-}
-
-function setQuestionSource(instanceId: string, requestId: string, source: QuestionSource): void {
-  let sources = questionSourceByInstance.get(instanceId)
-  if (!sources) {
-    sources = new Map()
-    questionSourceByInstance.set(instanceId, sources)
-  }
-  sources.set(requestId, source)
-}
-
-function getQuestionSource(instanceId: string, requestId: string): QuestionSource {
-  return questionSourceByInstance.get(instanceId)?.get(requestId) ?? "v2"
-}
-
-function deleteQuestionSource(instanceId: string, requestId: string): void {
-  const sources = questionSourceByInstance.get(instanceId)
-  if (!sources) return
-  sources.delete(requestId)
-  if (sources.size === 0) {
-    questionSourceByInstance.delete(instanceId)
-  }
-}
+const permissionRegistry = new InterruptionRegistry<PermissionRequest, PermissionSource>("v2")
+const questionRegistry = new InterruptionRegistry<QuestionRequest, QuestionSource>("v2")
 
 type InterruptionKind = "permission" | "question"
 
@@ -181,13 +227,97 @@ const MAX_LOG_ENTRIES = 1000
 
 const pendingDisposeRequests = new Map<string, Promise<boolean>>()
 const pendingRehydrations = new Map<string, Promise<void>>()
+const initialHydrations = new Map<string, Promise<void>>()
+const initialSessionHydrations = new Map<string, Promise<void>>()
+const initialWorkspaceMetadataHydrations = new Map<string, Promise<void>>()
+type RestoreWorkspaceDescriptor = WorkspaceDescriptor & { reused?: boolean }
+const workspaceListReconciliationFence = new WorkspaceListReconciliationFence()
+
+const restoreCreatedWorkspaceCleanup = new AbortCreatedWorkspaceCleanup<RestoreWorkspaceDescriptor>({
+  discardWorkspace: (workspace) => {
+    if (!workspace.requestId) return Promise.reject(new Error(`Restore workspace ${workspace.id} has no creation request`))
+    return serverApi.cancelWorkspaceCreation(workspace.requestId)
+  },
+  restoreWorkspace: (workspace) => {
+    workspaceListReconciliationFence.markMutation(workspace.id)
+    upsertWorkspace(workspace)
+  },
+  onPermanentFailure: (workspace, error) => {
+    log.error("Failed to cancel restore workspace ownership; restored it to the UI", {
+      workspaceId: workspace.id,
+      error,
+    })
+  },
+})
+let restoreCreationRequestSequence = 0
+const restoreCreationCommitGates = new RestoreWorkspaceCommitGates<RestoreWorkspaceDescriptor>()
+
+const connectionResyncs = new TrailingResyncCoordinator(
+  async (instanceId) => {
+    await waitForSettledPrerequisite(initialHydrations.get(instanceId))
+    const instance = instances().get(instanceId)
+    if (!instance?.client || instance.status !== "ready") return
+    await fetchSessions(instanceId, { reset: false })
+  },
+  (instanceId, error) => {
+    log.warn("Failed to resync sessions after instance connection", { instanceId, error })
+  },
+)
+
+function resyncConnectedInstance(instanceId: string): void {
+  void connectionResyncs.request(instanceId)
+}
+
+serverEvents.on("instance.eventStatus", (event) => {
+  if (event.type !== "instance.eventStatus" || event.status !== "connected") return
+  if (disconnectedInstance()?.id === event.instanceId) {
+    setDisconnectedInstance(null)
+  }
+  resyncConnectedInstance(event.instanceId)
+})
+
+function createRestoreCreationRequestId(): string {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return `restore-${globalThis.crypto.randomUUID()}`
+  }
+  restoreCreationRequestSequence += 1
+  return `restore-${Date.now().toString(36)}-${restoreCreationRequestSequence.toString(36)}`
+}
+
+type InstanceReadyWaiter = {
+  resolve: () => void
+  reject: (error: Error) => void
+}
+
+const instanceReadyWaiters = new Map<string, Set<InstanceReadyWaiter>>()
+
+function settleInstanceReadyWaiters(instanceId: string, error?: Error): void {
+  const waiters = instanceReadyWaiters.get(instanceId)
+  if (!waiters) return
+  instanceReadyWaiters.delete(instanceId)
+  for (const waiter of waiters) {
+    if (error) {
+      waiter.reject(error)
+    } else {
+      waiter.resolve()
+    }
+  }
+}
+
+function reconcilePendingSessionIndicators(instanceId: string): void {
+  reconcileSessionPendingState(
+    instanceId,
+    new Set(permissionRegistry.sessionIds(instanceId)),
+    new Set(questionRegistry.sessionIds(instanceId)),
+  )
+}
 
 function workspaceDescriptorToInstance(descriptor: WorkspaceDescriptor, projectName?: string): Instance {
   const existing = instances().get(descriptor.id)
   return {
     id: descriptor.id,
     folder: descriptor.path,
-    projectName: descriptor.name ?? projectName ?? existing?.projectName,
+    projectName: projectName ?? existing?.projectName ?? descriptor.name,
     port: descriptor.port ?? existing?.port ?? 0,
     pid: descriptor.pid ?? existing?.pid ?? 0,
     proxyPath: descriptor.proxyPath,
@@ -203,6 +333,7 @@ function workspaceDescriptorToInstance(descriptor: WorkspaceDescriptor, projectN
 }
 
 function ensureActiveInstanceSelected(): void {
+  if (appSessionRestoreGateActive()) return
   if (activeSidecarToken()) return
 
   const current = activeInstanceId()
@@ -230,6 +361,12 @@ function upsertWorkspace(descriptor: WorkspaceDescriptor, projectName?: string)
     // If no tab is currently selected (common after UI refresh),
     // auto-select the first ready instance.
     ensureActiveInstanceSelected()
+    settleInstanceReadyWaiters(descriptor.id)
+  } else if (descriptor.status === "error" || descriptor.status === "stopped") {
+    settleInstanceReadyWaiters(
+      descriptor.id,
+      new Error(descriptor.error || `Workspace ${descriptor.id} did not become ready`),
+    )
   }
 }
 
@@ -258,12 +395,66 @@ function attachClient(descriptor: WorkspaceDescriptor) {
     proxyPath: nextProxyPath,
     status: "ready",
   })
-  sseManager.seedStatus(descriptor.id, "connecting")
-  void hydrateInstanceData(descriptor.id).catch((error) => {
+  sseManager.seedStatusIfMissing(descriptor.id, "connecting")
+  const sessionHydration = startInstanceSessionHydration(descriptor.id)
+  initialSessionHydrations.set(descriptor.id, sessionHydration.sessions)
+  initialWorkspaceMetadataHydrations.set(descriptor.id, sessionHydration.workspaceMetadata)
+  const hydration = hydrateInstanceData(descriptor.id, {
+    propagateErrors: true,
+    sessionHydration: sessionHydration.sessions,
+    workspaceMetadataHydration: sessionHydration.workspaceMetadata,
+  })
+  initialHydrations.set(descriptor.id, hydration)
+  if (sseManager.getStatuses().get(descriptor.id) === "connected") {
+    resyncConnectedInstance(descriptor.id)
+  }
+  void hydration.catch((error) => {
     log.error("Failed to hydrate instance data", error)
   })
 }
 
+function waitForInstanceReady(instanceId: string): Promise<void> {
+  const instance = instances().get(instanceId)
+  if (instance?.status === "ready" && instance.client) {
+    return Promise.resolve()
+  }
+  if (instance?.status === "error" || instance?.status === "stopped") {
+    return Promise.reject(new Error(instance.error || `Workspace ${instanceId} did not become ready`))
+  }
+
+  return new Promise<void>((resolve, reject) => {
+    const waiter = { resolve, reject }
+    const waiters = instanceReadyWaiters.get(instanceId) ?? new Set<InstanceReadyWaiter>()
+    waiters.add(waiter)
+    instanceReadyWaiters.set(instanceId, waiters)
+
+    const current = instances().get(instanceId)
+    if (current?.status === "ready" && current.client) {
+      settleInstanceReadyWaiters(instanceId)
+    } else if (current?.status === "error" || current?.status === "stopped") {
+      settleInstanceReadyWaiters(
+        instanceId,
+        new Error(current.error || `Workspace ${instanceId} did not become ready`),
+      )
+    }
+  })
+}
+
+async function waitForInstanceInitialHydration(instanceId: string): Promise<void> {
+  await waitForInstanceReady(instanceId)
+  await initialHydrations.get(instanceId)
+}
+
+async function waitForInstanceInitialSessionHydration(instanceId: string): Promise<void> {
+  await waitForInstanceReady(instanceId)
+  await initialSessionHydrations.get(instanceId)
+}
+
+async function waitForInstanceWorkspaceMetadataHydration(instanceId: string): Promise<void> {
+  await waitForInstanceReady(instanceId)
+  await initialWorkspaceMetadataHydrations.get(instanceId)
+}
+
 function releaseInstanceResources(instanceId: string) {
   const instance = instances().get(instanceId)
   if (!instance) return
@@ -290,7 +481,7 @@ async function syncPendingPermissions(instanceId: string): Promise<void> {
       return []
     })
     for (const permission of legacyRemote) {
-      setPermissionSource(instanceId, permission.id, "legacy")
+      permissionRegistry.setSource(instanceId, permission.id, "legacy")
       remote.push({ request: permission, source: "legacy" })
     }
 
@@ -301,7 +492,7 @@ async function syncPendingPermissions(instanceId: string): Promise<void> {
       )
       log.info("v2.permission.request.list", { instanceId, location, resolvedLocation: response.location })
       for (const permission of response.data) {
-        setPermissionSource(instanceId, permission.id, "v2")
+        permissionRegistry.setSource(instanceId, permission.id, "v2")
         remote.push({ request: permission, source: "v2" })
       }
     }
@@ -326,7 +517,7 @@ async function syncPendingPermissions(instanceId: string): Promise<void> {
       const queuedPermission = addPermissionToQueue(instanceId, permission, source) ?? permission
       upsertPermissionV2(instanceId, queuedPermission)
     }
-    drainAutoAcceptPermissions(instanceId, getPermissionQueue(instanceId), sendPermissionResponse, hasPendingPermission)
+    reconcilePendingSessionIndicators(instanceId)
   } catch (error) {
     log.warn("Failed to sync pending permissions", { instanceId, error })
   }
@@ -346,7 +537,7 @@ async function syncPendingQuestions(instanceId: string): Promise<void> {
       return []
     })
     for (const request of legacyRemote) {
-      setQuestionSource(instanceId, request.id, "legacy")
+      questionRegistry.setSource(instanceId, request.id, "legacy")
       remote.push({ request, source: "legacy" })
     }
 
@@ -357,7 +548,7 @@ async function syncPendingQuestions(instanceId: string): Promise<void> {
       )
       log.info("v2.question.request.list", { instanceId, location, resolvedLocation: response.location })
       for (const request of response.data) {
-        setQuestionSource(instanceId, request.id, "v2")
+        questionRegistry.setSource(instanceId, request.id, "v2")
         remote.push({ request, source: "v2" })
       }
     }
@@ -375,27 +566,53 @@ async function syncPendingQuestions(instanceId: string): Promise<void> {
 
     // Upsert all server-side pending questions.
     for (const { request, source } of remote) {
-      ensureQuestionEnqueuedAt(request)
+      questionRegistry.ensureEnqueuedAt(request)
       addQuestionToQueue(instanceId, request, source)
       upsertQuestionV2(instanceId, request)
     }
+    reconcilePendingSessionIndicators(instanceId)
   } catch (error) {
     log.warn("Failed to sync pending questions", { instanceId, error })
   }
 }
 
-async function hydrateInstanceData(instanceId: string, options?: { force?: boolean }) {
-  try {
-    if (options?.force) {
-      await reloadWorktrees(instanceId)
-      await reloadWorktreeMap(instanceId)
-    } else {
-      await ensureWorktreesLoaded(instanceId)
-      await ensureWorktreeMapLoaded(instanceId)
-    }
-    await syncOpenCodeWorkspaces(instanceId)
+function startInstanceSessionHydration(instanceId: string, force = false): {
+  sessions: Promise<void>
+  workspaceMetadata: Promise<void>
+} {
+  const worktreeMapHydration = force
+    ? reloadWorktreeMap(instanceId)
+    : ensureWorktreeMapLoaded(instanceId)
+  const worktreeHydration = force
+    ? reloadWorktrees(instanceId)
+    : ensureWorktreesLoaded(instanceId)
+  const sessions = Promise.all([worktreeHydration, worktreeMapHydration]).then(async () => {
     resetSessionPagination(instanceId)
-    await fetchSessions(instanceId)
+    await fetchSessions(instanceId).catch((error) => {
+      log.error("Failed to hydrate sessions", { instanceId, error })
+    })
+  })
+  const workspaceMetadata = worktreeHydration.then(async () => {
+    await Promise.all([worktreeMapHydration, syncOpenCodeWorkspaces(instanceId)])
+  })
+  return { sessions, workspaceMetadata }
+}
+
+async function hydrateInstanceData(instanceId: string, options?: {
+  force?: boolean
+  propagateErrors?: boolean
+  sessionHydration?: Promise<void>
+  workspaceMetadataHydration?: Promise<void>
+}) {
+  try {
+    const hydration = options?.sessionHydration
+      ? {
+          sessions: options.sessionHydration,
+          workspaceMetadata: options.workspaceMetadataHydration ?? Promise.resolve(),
+        }
+      : startInstanceSessionHydration(instanceId, options?.force)
+    await hydration.sessions
+    await hydration.workspaceMetadata
     await fetchAgents(instanceId)
     await fetchProviders(instanceId)
     await ensureInstanceConfigLoaded(instanceId)
@@ -406,6 +623,7 @@ async function hydrateInstanceData(instanceId: string, options?: { force?: boole
     await syncPendingQuestions(instanceId)
   } catch (error) {
     log.error("Failed to fetch initial data", error)
+    if (options?.propagateErrors) throw error
   }
 }
 
@@ -447,6 +665,15 @@ async function postInstanceDispose(instanceId: string): Promise<boolean> {
   return Boolean(text)
 }
 
+function clearReloadableInstanceState(instanceId: string): void {
+  clearCacheForInstance(instanceId)
+  clearCommands(instanceId)
+  clearInstanceMetadata(instanceId)
+  messageStoreBus.clearInstanceScrollSnapshots(instanceId)
+  clearPermissionQueue(instanceId)
+  clearQuestionQueue(instanceId)
+}
+
 async function rehydrateInstance(instanceId: string, options?: { reason?: string }): Promise<void> {
   if (pendingRehydrations.has(instanceId)) {
     return pendingRehydrations.get(instanceId)
@@ -459,12 +686,7 @@ async function rehydrateInstance(instanceId: string, options?: { reason?: string
     }
 
     log.info("Rehydrating instance", { instanceId, reason: options?.reason })
-    clearCacheForInstance(instanceId)
-    clearCommands(instanceId)
-    clearInstanceMetadata(instanceId)
-    clearInstanceDraftPrompts(instanceId)
-    clearPermissionQueue(instanceId)
-    clearQuestionQueue(instanceId)
+    clearReloadableInstanceState(instanceId)
 
     await hydrateInstanceData(instanceId, { force: true })
   })().finally(() => {
@@ -494,21 +716,94 @@ async function disposeInstance(instanceId: string): Promise<boolean> {
   return promise
 }
 
-  void (async function initializeWorkspaces() {
+async function refreshWorkspaceList(): Promise<void> {
+  const requestFence = workspaceListReconciliationFence.begin()
+  const removalCandidates = new Set(instances().keys())
   try {
     const workspaces = await serverApi.fetchWorkspaces()
-    workspaces.forEach((workspace) => upsertWorkspace(workspace))
-    // After a UI refresh, we may have instances but no active selection.
+    if (!workspaceListReconciliationFence.isCurrent(requestFence)) return
+    const remoteIds = new Set(workspaces.map(({ id }) => id))
+    for (const workspace of workspaces) {
+      if (!workspaceListReconciliationFence.allows(requestFence, workspace.id)) continue
+      restoreCreatedWorkspaceCleanup.trackPendingRequest(workspace)
+      if (restoreCreationCommitGates.deferRefreshWorkspace(workspace)) continue
+      if (restoreCreatedWorkspaceCleanup.owns(workspace.id)) {
+        restoreCreatedWorkspaceCleanup.track(workspace)
+        continue
+      }
+      upsertWorkspace(workspace)
+    }
+    const unchangedCandidates = [...removalCandidates]
+      .filter((id) => workspaceListReconciliationFence.allows(requestFence, id))
+    for (const instanceId of getUnavailableWorkspaceIds(
+      unchangedCandidates, remoteIds, (id) => restoreCreatedWorkspaceCleanup.owns(id),
+    )) {
+      releaseInstanceResources(instanceId)
+      removeInstance(instanceId, { authoritative: false })
+    }
     ensureActiveInstanceSelected()
+  } finally {
+    workspaceListReconciliationFence.complete(requestFence)
+  }
+}
+
+const initialWorkspaceLoad = (async function initializeWorkspaces(): Promise<{ error?: unknown }> {
+  try {
+    await refreshWorkspaceList()
+    return {}
   } catch (error) {
     log.error("Failed to load workspaces", error)
+    return { error }
   }
 })()
+let latestWorkspaceLoad = initialWorkspaceLoad
+
+serverEvents.onOpen(() => {
+  latestWorkspaceLoad = refreshWorkspaceList().then(
+    () => ({}),
+    (error) => {
+      log.warn("Failed to reconcile workspaces after event reconnect", error)
+      return { error }
+    },
+  )
+})
+
+async function waitForInitialWorkspaceLoad(): Promise<void> {
+  let load = initialWorkspaceLoad
+  while (true) {
+    const result = await load
+    if (result.error !== undefined) throw result.error
+    if (load === latestWorkspaceLoad) return
+    load = latestWorkspaceLoad
+  }
+}
 
 
 serverEvents.on("*", (event) => handleWorkspaceEvent(event))
 
 function handleWorkspaceEvent(event: WorkspaceEventPayload) {
+  const workspaceId = event.type === "workspace.log"
+    ? event.entry.workspaceId
+    : "workspace" in event
+      ? event.workspace.id
+      : "workspaceId" in event && typeof event.workspaceId === "string"
+        ? event.workspaceId
+        : null
+  if (workspaceId && event.type !== "workspace.log") {
+    workspaceListReconciliationFence.markMutation(workspaceId)
+  }
+  if ("workspace" in event) {
+    restoreCreatedWorkspaceCleanup.trackPendingRequest(event.workspace)
+    if (restoreCreationCommitGates.deferWorkspace(event.workspace)) return
+  }
+  if (event.type === "workspace.stopped"
+    && restoreCreationCommitGates.deferStopped(event.workspaceId, event.reason)) {
+    return
+  }
+  if (workspaceId && restoreCreatedWorkspaceCleanup.shouldIgnoreEvent(workspaceId)) {
+    return
+  }
+
   switch (event.type) {
     case "workspace.created":
       upsertWorkspace(event.workspace)
@@ -519,10 +814,13 @@ function handleWorkspaceEvent(event: WorkspaceEventPayload) {
     case "workspace.error":
       upsertWorkspace(event.workspace)
       showWorkspaceLaunchError(event.workspace)
+      clearPermissionAutoAcceptForInstance(event.workspace.id)
+      clearSyncedYoloSessionsForInstance(event.workspace.id)
       break
     case "workspace.stopped":
+      restoreCreatedWorkspaceCleanup.release(event.workspaceId)
       releaseInstanceResources(event.workspaceId)
-      removeInstance(event.workspaceId)
+      removeInstance(event.workspaceId, { authoritative: event.reason === "deleted" })
       break
     case "workspace.log":
       handleWorkspaceLog(event.entry)
@@ -603,6 +901,9 @@ function setInstanceLogStreaming(instanceId: string, enabled: boolean) {
 }
 
 function addInstance(instance: Instance) {
+  const occurrence = Array.from(instances().values())
+    .filter((existing) => normalizeInstanceFolderPath(existing.folder) === normalizeInstanceFolderPath(instance.folder))
+    .length
   setInstances((prev) => {
     const next = new Map(prev)
     next.set(instance.id, instance)
@@ -610,6 +911,12 @@ function addInstance(instance: Instance) {
   })
   ensureLogContainer(instance.id)
   ensureLogStreamingState(instance.id)
+  publishInstanceLifecycleAuthority({
+    type: "opened",
+    instanceId: instance.id,
+    folder: instance.folder,
+    occurrence,
+  })
   syncHasInstancesFlag()
 }
 
@@ -625,7 +932,21 @@ function updateInstance(id: string, updates: Partial<Instance>) {
   syncHasInstancesFlag()
 }
 
-function removeInstance(id: string) {
+function removeInstance(id: string, options: { authoritative?: boolean } = {}) {
+  const removedInstance = instances().get(id)
+  const removedOccurrence = removedInstance
+    ? Array.from(instances().values())
+        .filter((instance) => normalizeInstanceFolderPath(instance.folder) === normalizeInstanceFolderPath(removedInstance.folder))
+        .findIndex((instance) => instance.id === id)
+    : -1
+  if (removedInstance && removedOccurrence >= 0 && options.authoritative === false) {
+    publishInstanceLifecycleAuthority({
+      type: "unavailable",
+      instanceId: id,
+      folder: removedInstance.folder,
+      occurrence: removedOccurrence,
+    })
+  }
   let nextActiveId: string | null = null
 
   setInstances((prev) => {
@@ -657,6 +978,12 @@ function removeInstance(id: string) {
   clearRepliedPermissions(id)
   clearQuestionQueue(id)
   clearInstanceMetadata(id)
+  clearPermissionAutoAcceptForInstance(id)
+  clearSyncedYoloSessionsForInstance(id)
+  initialHydrations.delete(id)
+  initialSessionHydrations.delete(id)
+  initialWorkspaceMetadataHydrations.delete(id)
+  settleInstanceReadyWaiters(id, new Error(`Workspace ${id} was removed before it became ready`))
 
   if (activeInstanceId() === id) {
     setActiveInstanceId(nextActiveId)
@@ -666,18 +993,193 @@ function removeInstance(id: string) {
   clearCacheForInstance(id)
   messageStoreBus.unregisterInstance(id)
   clearInstanceDraftPrompts(id)
+  clearSessionListRequestState(id)
+  clearInstanceAttachments(id)
+  clearInstanceDeletedSessionAuthority(id)
+  clearInstanceSessionExpansionState(id)
+  clearInstanceSessionSelection(id)
+  if (removedInstance && removedOccurrence >= 0 && options.authoritative !== false) {
+    publishInstanceLifecycleAuthority({
+      type: "removed",
+      instanceId: id,
+      folder: removedInstance.folder,
+      occurrence: removedOccurrence,
+    })
+  }
   syncHasInstancesFlag()
 }
 
-async function createInstance(folder: string, _binaryPath?: string, projectName?: string): Promise<string> {
+function removeRestoreCreatedInstanceFromUi(instanceId: string): void {
+  workspaceListReconciliationFence.markMutation(instanceId)
+  if (instances().has(instanceId)) {
+    releaseInstanceResources(instanceId)
+    removeInstance(instanceId, { authoritative: false })
+  }
+}
+
+function disposeRestoreWorkspaceResponse(workspace: RestoreWorkspaceDescriptor): Promise<void> {
+  if (workspace.reused !== true) removeRestoreCreatedInstanceFromUi(workspace.id)
+  return restoreCreatedWorkspaceCleanup.discardCreated(workspace, { retainTombstone: workspace.reused !== true })
+}
+
+function disposeRestoreCreatedInstance(instanceId: string): Promise<void> {
+  const workspace = restoreCreatedWorkspaceCleanup.get(instanceId)
+  if (!workspace) return Promise.resolve()
+  if (workspace.reused !== true) removeRestoreCreatedInstanceFromUi(instanceId)
+  return restoreCreatedWorkspaceCleanup.discardTracked(instanceId, { retainTombstone: workspace.reused !== true })
+}
+
+async function releaseRestoreCreatedInstance(instanceId: string, requestId: string): Promise<void> {
+  await restoreCreatedWorkspaceCleanup.releaseAfter(instanceId, () =>
+    retryWithBackoff(() => serverApi.releaseWorkspaceCreation(instanceId, requestId), {
+      maxAttempts: 4,
+      initialDelayMs: 250,
+      maxDelayMs: 2_000,
+      backoffMultiplier: 4,
+    }))
+}
+
+async function cancelRestoreCreationRequest(instanceId: string | undefined, requestId: string): Promise<void> {
+  await cancelRestoreCreation(requestId)
+  if (instanceId) restoreCreatedWorkspaceCleanup.forgetRequest(instanceId, requestId)
+}
+
+function claimRestoreCreatedInstanceForUser(instanceId: string): void {
+  const workspace = restoreCreatedWorkspaceCleanup.get(instanceId)
+  if (!workspace?.requestId) return
+  void releaseRestoreCreatedInstance(instanceId, workspace.requestId).catch((error) => {
+    log.warn("Failed to transfer restore workspace creation ownership to the user", { instanceId, error })
+  })
+}
+
+async function settleRestoreWorkspaceTerminal(
+  workspace: RestoreWorkspaceDescriptor,
+  terminal: RestoreWorkspaceTerminal,
+): Promise<void> {
+  if (terminal.status === "stopped") {
+    restoreCreatedWorkspaceCleanup.release(workspace.id)
+    removeRestoreCreatedInstanceFromUi(workspace.id)
+    return
+  }
+  await disposeRestoreWorkspaceResponse(workspace)
+}
+
+async function createInstance(
+  folder: string,
+  binaryPath?: string,
+  projectName?: string,
+  options?: {
+    activate?: boolean
+    signal?: AbortSignal
+    shouldCreateCommit?: () => boolean
+    onCreateCommit?: (instanceId: string) => void
+    waitForCreateCommit?: () => Promise<void>
+    forceNew?: boolean
+  },
+): Promise<{ instanceId: string; reused: boolean; requestId?: string }> {
+  const restoreRequestId = options?.signal ? createRestoreCreationRequestId() : undefined
+  if (restoreRequestId) restoreCreatedWorkspaceCleanup.beginRequest(restoreRequestId)
+  const commitGate: RestoreWorkspaceCommitGate<RestoreWorkspaceDescriptor> | undefined = restoreRequestId && options?.waitForCreateCommit
+    ? restoreCreationCommitGates.begin(restoreRequestId, options.waitForCreateCommit(), folder)
+    : undefined
+  let cancellationRequest: Promise<boolean> | null = null
+  let requestResolved = false
+  let terminalHandled = false
+  const cancelPendingCreation = () => {
+    if (!restoreRequestId) return
+    const trackedCleanup = restoreCreatedWorkspaceCleanup.quarantineRequest(restoreRequestId)
+    cancellationRequest ??= trackedCleanup
+      ? trackedCleanup.then(() => true)
+      : cancelRestoreCreationRequest(undefined, restoreRequestId)
+          .then(() => true, (error) => {
+            log.warn("Failed to cancel restore workspace creation", { requestId: restoreRequestId, error })
+            return false
+          })
+  }
+  options?.signal?.addEventListener("abort", cancelPendingCreation, { once: true })
+
   try {
-    const workspace = await serverApi.createWorkspace({ path: folder, name: projectName })
-    upsertWorkspace(workspace, projectName)
-    setActiveInstanceId(workspace.id)
-    return workspace.id
+    if (options?.signal?.aborted) throw getAbortReason(options.signal)
+    const workspace = await serverApi.createWorkspace({
+      path: folder,
+      name: projectName,
+      binaryPath,
+      requestId: restoreRequestId,
+      forceNew: options?.forceNew,
+    }, { signal: options?.signal })
+    requestResolved = true
+    const reused = workspace.reused === true
+    if (restoreRequestId) restoreCreationCommitGates.bindResponse(restoreRequestId, workspace.id)
+    if (options?.signal?.aborted) {
+      if (workspace.requestId) await disposeRestoreWorkspaceResponse(workspace)
+      throw getAbortReason(options.signal)
+    }
+    if (options?.signal && workspace.requestId) {
+      const observed = restoreRequestId
+        ? restoreCreationCommitGates.resolve(restoreRequestId, workspace).workspace
+        : workspace
+      restoreCreatedWorkspaceCleanup.track({
+        ...observed,
+        requestId: observed.requestId ?? workspace.requestId,
+        ...(reused ? { reused: true as const } : {}),
+      })
+    }
+    else if (!options?.signal) restoreCreatedWorkspaceCleanup.releaseTombstoneForUserCreate(workspace.id)
+    if (commitGate) await commitGate.wait
+    if (options?.signal?.aborted) {
+      if (workspace.requestId) await disposeRestoreWorkspaceResponse(workspace)
+      throw getAbortReason(options.signal)
+    }
+    const resolution = restoreRequestId
+      ? restoreCreationCommitGates.resolve(restoreRequestId, workspace)
+      : { workspace }
+    const committedWorkspace: RestoreWorkspaceDescriptor = {
+      ...resolution.workspace,
+      requestId: resolution.workspace.requestId ?? workspace.requestId,
+      ...(reused ? { reused: true } : {}),
+    }
+    if (restoreRequestId) restoreCreatedWorkspaceCleanup.track(committedWorkspace)
+    const terminal = resolution.terminal ?? (committedWorkspace.status === "error" || committedWorkspace.status === "stopped"
+      ? { status: committedWorkspace.status, message: committedWorkspace.error }
+      : undefined)
+    if (terminal) {
+      terminalHandled = true
+      await settleRestoreWorkspaceTerminal(committedWorkspace, terminal)
+      throw new Error(terminal.message || `Restore-created workspace ${workspace.id} ${terminal.status}`)
+    }
+    const discarded = restoreCreatedWorkspaceCleanup.shouldIgnoreEvent(workspace.id)
+      || options?.shouldCreateCommit?.() === false
+    if (!discarded) {
+      workspaceListReconciliationFence.markMutation(workspace.id)
+      upsertWorkspace(committedWorkspace, reused ? undefined : projectName)
+      options?.onCreateCommit?.(workspace.id)
+      if (!reused && (options?.activate ?? true)) setActiveInstanceId(workspace.id)
+    }
+    if (discarded) {
+      if (workspace.requestId) await disposeRestoreWorkspaceResponse(workspace)
+      throw new Error(`Restore-created workspace ${workspace.id} was closed before startup completed`)
+    }
+    return { instanceId: workspace.id, reused, requestId: workspace.requestId }
   } catch (error) {
-    log.error("Failed to create workspace", error)
+    if (!terminalHandled && commitGate?.terminal && commitGate.workspace) {
+      terminalHandled = true
+      await settleRestoreWorkspaceTerminal(commitGate.workspace, commitGate.terminal)
+    }
+    if (!options?.signal?.aborted) log.error("Failed to create workspace", error)
     throw error
+  } finally {
+    options?.signal?.removeEventListener("abort", cancelPendingCreation)
+    if (restoreRequestId) {
+      restoreCreationCommitGates.end(restoreRequestId)
+      const pendingCancellation = cancellationRequest as Promise<boolean> | null
+      if (requestResolved || !pendingCancellation) {
+        restoreCreatedWorkspaceCleanup.finishRequest(restoreRequestId)
+      } else {
+        void pendingCancellation.then((cancelled) => {
+          if (cancelled) restoreCreatedWorkspaceCleanup.finishRequest(restoreRequestId)
+        })
+      }
+    }
   }
 }
 
@@ -721,9 +1223,17 @@ function stopInstance(id: string) {
   const instance = instances().get(id)
   if (!instance) return
 
+  workspaceListReconciliationFence.markMutation(id)
   releaseInstanceResources(id)
   removeInstance(id)
 
+  if (restoreCreatedWorkspaceCleanup.owns(id)) {
+    void restoreCreatedWorkspaceCleanup.discardTracked(id, { retainTombstone: true })
+      .then(() => serverApi.deleteWorkspace(id))
+      .catch((error) => log.error("Failed to stop restore-tracked workspace", error))
+    return
+  }
+
   void serverApi.deleteWorkspace(id).catch((error) => {
     log.error("Failed to stop workspace", error)
     showToastNotification({
@@ -816,18 +1326,18 @@ function getQuestionEnqueuedAtForInstance(instanceId: string, requestId: string)
   const queue = getQuestionQueue(instanceId)
   const match = queue.find((q) => q.id === requestId)
   if (match) {
-    return ensureQuestionEnqueuedAt(match)
+    return questionRegistry.ensureEnqueuedAt(match)
   }
-  return questionEnqueuedAt.get(requestId) ?? Date.now()
+  return questionRegistry.enqueuedAtFor(requestId)
 }
 
 function getPermissionEnqueuedAtForInstance(instanceId: string, permissionId: string): number {
   const queue = getPermissionQueue(instanceId)
   const match = queue.find((permission) => permission.id === permissionId)
   if (match) {
-    return ensurePermissionEnqueuedAt(match)
+    return permissionRegistry.ensureEnqueuedAt(match)
   }
-  return permissionEnqueuedAt.get(permissionId) ?? Date.now()
+  return permissionRegistry.enqueuedAtFor(permissionId)
 }
 
 function computeActiveInterruption(instanceId: string): ActiveInterruption {
@@ -839,8 +1349,8 @@ function computeActiveInterruption(instanceId: string): ActiveInterruption {
   if (firstPermission && !firstQuestion) return { kind: "permission", id: firstPermission.id }
   if (firstQuestion && !firstPermission) return { kind: "question", id: firstQuestion.id }
 
-  const permTime = firstPermission ? ensurePermissionEnqueuedAt(firstPermission) : Number.MAX_SAFE_INTEGER
-  const quesTime = firstQuestion ? ensureQuestionEnqueuedAt(firstQuestion) : Number.MAX_SAFE_INTEGER
+  const permTime = firstPermission ? permissionRegistry.ensureEnqueuedAt(firstPermission) : Number.MAX_SAFE_INTEGER
+  const quesTime = firstQuestion ? questionRegistry.ensureEnqueuedAt(firstQuestion) : Number.MAX_SAFE_INTEGER
   if (permTime <= quesTime) return { kind: "permission", id: firstPermission.id }
   return { kind: "question", id: firstQuestion!.id }
 }
@@ -881,82 +1391,12 @@ function recomputeActiveInterruption(instanceId: string): void {
   setActiveInterruptionForInstance(instanceId, computeActiveInterruption(instanceId))
 }
 
-function incrementSessionPendingCount(instanceId: string, sessionId: string): void {
-  let sessionCounts = permissionSessionCounts.get(instanceId)
-  if (!sessionCounts) {
-    sessionCounts = new Map()
-    permissionSessionCounts.set(instanceId, sessionCounts)
-  }
-  const current = sessionCounts.get(sessionId) ?? 0
-  sessionCounts.set(sessionId, current + 1)
-}
-
-function decrementSessionPendingCount(instanceId: string, sessionId: string): number {
-  const sessionCounts = permissionSessionCounts.get(instanceId)
-  if (!sessionCounts) return 0
-  const current = sessionCounts.get(sessionId) ?? 0
-  if (current <= 1) {
-    sessionCounts.delete(sessionId)
-    if (sessionCounts.size === 0) {
-      permissionSessionCounts.delete(instanceId)
-    }
-    return 0
-  }
-  const nextValue = current - 1
-  sessionCounts.set(sessionId, nextValue)
-  return nextValue
-}
-
-function clearSessionPendingCounts(instanceId: string): void {
-  const sessionCounts = permissionSessionCounts.get(instanceId)
-  if (!sessionCounts) return
-  for (const sessionId of sessionCounts.keys()) {
-    setSessionPendingPermission(instanceId, sessionId, false)
-  }
-  permissionSessionCounts.delete(instanceId)
-}
-
-function incrementQuestionSessionPendingCount(instanceId: string, sessionId: string): void {
-  let sessionCounts = questionSessionCounts.get(instanceId)
-  if (!sessionCounts) {
-    sessionCounts = new Map()
-    questionSessionCounts.set(instanceId, sessionCounts)
-  }
-  const current = sessionCounts.get(sessionId) ?? 0
-  sessionCounts.set(sessionId, current + 1)
-}
-
-function decrementQuestionSessionPendingCount(instanceId: string, sessionId: string): number {
-  const sessionCounts = questionSessionCounts.get(instanceId)
-  if (!sessionCounts) return 0
-  const current = sessionCounts.get(sessionId) ?? 0
-  if (current <= 1) {
-    sessionCounts.delete(sessionId)
-    if (sessionCounts.size === 0) {
-      questionSessionCounts.delete(instanceId)
-    }
-    return 0
-  }
-  const nextValue = current - 1
-  sessionCounts.set(sessionId, nextValue)
-  return nextValue
-}
-
-function clearQuestionSessionPendingCounts(instanceId: string): void {
-  const sessionCounts = questionSessionCounts.get(instanceId)
-  if (!sessionCounts) return
-  for (const sessionId of sessionCounts.keys()) {
-    setSessionPendingQuestion(instanceId, sessionId, false)
-  }
-  questionSessionCounts.delete(instanceId)
-}
-
-function addPermissionToQueue(instanceId: string, permission: PermissionRequest, source: PermissionSource = "v2"): PermissionRequest | undefined {
+function addPermissionToQueue(instanceId: string, permission: PermissionRequest, source?: PermissionSource): PermissionRequest | undefined {
   let inserted = false
   let updated = false
   let previousPermission: PermissionRequest | undefined
   let queuedPermission = permission
-  setPermissionSource(instanceId, permission.id, source)
+  if (source) permissionRegistry.setSource(instanceId, permission.id, source)
 
   setPermissionQueues((prev) => {
     const next = new Map(prev)
@@ -968,13 +1408,13 @@ function addPermissionToQueue(instanceId: string, permission: PermissionRequest,
       queuedPermission = mergePermissionRequest(previousPermission, permission)
       const updatedQueue = queue.slice()
       updatedQueue[existingIndex] = queuedPermission
-      next.set(instanceId, updatedQueue.sort((a, b) => ensurePermissionEnqueuedAt(a) - ensurePermissionEnqueuedAt(b)))
+      next.set(instanceId, updatedQueue.sort((a, b) => permissionRegistry.ensureEnqueuedAt(a) - permissionRegistry.ensureEnqueuedAt(b)))
       updated = true
       return next
     }
 
-    ensurePermissionEnqueuedAt(queuedPermission)
-    const updatedQueue = [...queue, queuedPermission].sort((a, b) => ensurePermissionEnqueuedAt(a) - ensurePermissionEnqueuedAt(b))
+    permissionRegistry.ensureEnqueuedAt(queuedPermission)
+    const updatedQueue = [...queue, queuedPermission].sort((a, b) => permissionRegistry.ensureEnqueuedAt(a) - permissionRegistry.ensureEnqueuedAt(b))
     next.set(instanceId, updatedQueue)
     inserted = true
     return next
@@ -989,19 +1429,18 @@ function addPermissionToQueue(instanceId: string, permission: PermissionRequest,
   const previousSessionId = previousPermission ? getPermissionSessionId(previousPermission) : undefined
   const sessionId = getPermissionSessionId(queuedPermission)
   if (previousSessionId && previousSessionId !== sessionId) {
-    const remaining = decrementSessionPendingCount(instanceId, previousSessionId)
+    const remaining = permissionRegistry.decrement(instanceId, previousSessionId)
     setSessionPendingPermission(instanceId, previousSessionId, remaining > 0)
   }
 
   if (sessionId) {
     if (inserted || previousSessionId !== sessionId) {
-      incrementSessionPendingCount(instanceId, sessionId)
+      permissionRegistry.increment(instanceId, sessionId)
     }
     setSessionPendingPermission(instanceId, sessionId, true)
 
   }
 
-  drainAutoAcceptPermissions(instanceId, [queuedPermission], sendPermissionResponse, hasPendingPermission)
   return queuedPermission
 }
 
@@ -1030,42 +1469,77 @@ function removePermissionFromQueue(instanceId: string, permissionId: string): vo
   })
 
   recomputeActiveInterruption(instanceId)
-  permissionEnqueuedAt.delete(permissionId)
-  deletePermissionSource(instanceId, permissionId)
+  permissionRegistry.remove(instanceId, permissionId)
 
   const removed = removedPermission
   if (removed) {
     const removedSessionId = getPermissionSessionId(removed)
     if (removedSessionId) {
-      clearAutoAcceptPermission(instanceId, removedSessionId, permissionId)
-      const remaining = decrementSessionPendingCount(instanceId, removedSessionId)
+      const remaining = permissionRegistry.decrement(instanceId, removedSessionId)
       setSessionPendingPermission(instanceId, removedSessionId, remaining > 0)
     }
   }
 }
 
 function togglePermissionAutoAcceptForSession(instanceId: string, sessionId: string): void {
-  const willEnable = !isPermissionAutoAcceptEnabled(instanceId, sessionId)
+  const wasEnabled = isPermissionAutoAcceptEnabled(instanceId, sessionId)
   togglePermissionAutoAccept(instanceId, sessionId)
-  if (!willEnable) return
-  drainAutoAcceptPermissionsForInstance(instanceId)
+  void serverApi
+    .toggleYolo(instanceId, sessionId)
+    .then((state) => {
+      setPermissionAutoAcceptEnabled(instanceId, sessionId, state.enabled)
+    })
+    .catch((error) => {
+      log.warn("Failed to toggle Yolo on server", { instanceId, sessionId, error })
+      // revert to the pre-toggle state (not a naive flip, which can be wrong
+      // if an SSE yolo.stateChanged arrived between toggle and catch)
+      setPermissionAutoAcceptEnabled(instanceId, sessionId, wasEnabled)
+    })
 }
 
-function drainAutoAcceptPermissionsForInstance(instanceId: string): void {
-  drainAutoAcceptPermissions(instanceId, getPermissionQueue(instanceId), sendPermissionResponse, hasPendingPermission)
+/**
+ * Sessions whose Yolo state has been backfilled from the server. The server is
+ * authoritative but only pushes changes (`yolo.stateChanged`); a freshly
+ * connected client must fetch the effective state for a session so the badge
+ * matches reality from the start. De-duped per session and reset on SSE
+ * reconnect so state re-syncs after a server restart.
+ */
+const syncedYoloSessions = new Set<string>()
+
+export function ensureYoloStateSynced(instanceId: string, sessionId: string): void {
+  if (!instanceId || !sessionId || sessionId === "info") return
+  const key = `${instanceId}:${sessionId}`
+  if (syncedYoloSessions.has(key)) return
+  syncedYoloSessions.add(key)
+  void serverApi
+    .getYoloState(instanceId, sessionId)
+    .then((state) => {
+      setPermissionAutoAcceptEnabled(instanceId, sessionId, state.enabled)
+    })
+    .catch((error) => {
+      // allow retry on next activation (e.g. instance not ready yet)
+      syncedYoloSessions.delete(key)
+      log.warn("Failed to sync Yolo state", { instanceId, sessionId, error })
+    })
+}
+
+serverEvents.onOpen(() => {
+  syncedYoloSessions.clear()
+})
+
+function clearSyncedYoloSessionsForInstance(instanceId: string): void {
+  const prefix = `${instanceId}:`
+  for (const key of Array.from(syncedYoloSessions)) {
+    if (key.startsWith(prefix)) {
+      syncedYoloSessions.delete(key)
+    }
+  }
 }
 
 function clearPermissionQueue(instanceId: string): void {
-  for (const permission of getPermissionQueue(instanceId)) {
-    const sessionId = getPermissionSessionId(permission)
-    if (sessionId) {
-      clearAutoAcceptPermission(instanceId, sessionId, permission.id)
-    }
-  }
-  for (const permission of getPermissionQueue(instanceId)) {
-    permissionEnqueuedAt.delete(permission.id)
-  }
-  permissionSourceByInstance.delete(instanceId)
+  permissionRegistry.clear(instanceId, getPermissionQueue(instanceId), (sessionId) => {
+    setSessionPendingPermission(instanceId, sessionId, false)
+  })
   setPermissionQueues((prev) => {
     const next = new Map(prev)
     next.delete(instanceId)
@@ -1076,13 +1550,12 @@ function clearPermissionQueue(instanceId: string): void {
     next.delete(instanceId)
     return next
   })
-  clearSessionPendingCounts(instanceId)
   recomputeActiveInterruption(instanceId)
 }
 
 function addQuestionToQueue(instanceId: string, request: QuestionRequest, source: QuestionSource = "v2"): void {
   let inserted = false
-  setQuestionSource(instanceId, request.id, source)
+  questionRegistry.setSource(instanceId, request.id, source)
 
   setQuestionQueues((prev) => {
     const next = new Map(prev)
@@ -1092,9 +1565,9 @@ function addQuestionToQueue(instanceId: string, request: QuestionRequest, source
       return next
     }
 
-    ensureQuestionEnqueuedAt(request)
+    questionRegistry.ensureEnqueuedAt(request)
     const updatedQueue = [...queue, request].sort((a, b) => {
-      return ensureQuestionEnqueuedAt(a) - ensureQuestionEnqueuedAt(b)
+      return questionRegistry.ensureEnqueuedAt(a) - questionRegistry.ensureEnqueuedAt(b)
     })
     next.set(instanceId, updatedQueue)
     inserted = true
@@ -1109,7 +1582,7 @@ function addQuestionToQueue(instanceId: string, request: QuestionRequest, source
 
   const sessionId = getQuestionSessionId(request)
   if (sessionId) {
-    incrementQuestionSessionPendingCount(instanceId, sessionId)
+    questionRegistry.increment(instanceId, sessionId)
     setSessionPendingQuestion(instanceId, sessionId, true)
 
   }
@@ -1131,21 +1604,19 @@ function removeQuestionFromQueue(instanceId: string, requestId: string): void {
     return next
   })
 
-  questionEnqueuedAt.delete(requestId)
-  deleteQuestionSource(instanceId, requestId)
+  questionRegistry.remove(instanceId, requestId)
   recomputeActiveInterruption(instanceId)
 
   if (removedSessionId) {
-    const remaining = decrementQuestionSessionPendingCount(instanceId, removedSessionId)
+    const remaining = questionRegistry.decrement(instanceId, removedSessionId)
     setSessionPendingQuestion(instanceId, removedSessionId, remaining > 0)
   }
 }
 
 function clearQuestionQueue(instanceId: string): void {
-  for (const request of getQuestionQueue(instanceId)) {
-    questionEnqueuedAt.delete(request.id)
-  }
-  questionSourceByInstance.delete(instanceId)
+  questionRegistry.clear(instanceId, getQuestionQueue(instanceId), (sessionId) => {
+    setSessionPendingQuestion(instanceId, sessionId, false)
+  })
   setQuestionQueues((prev) => {
     const next = new Map(prev)
     next.delete(instanceId)
@@ -1156,7 +1627,6 @@ function clearQuestionQueue(instanceId: string): void {
     next.delete(instanceId)
     return next
   })
-  clearQuestionSessionPendingCounts(instanceId)
   recomputeActiveInterruption(instanceId)
 }
 
@@ -1181,7 +1651,7 @@ async function sendQuestionReply(
 
   try {
     const client = getRootClient(instanceId)
-    const source = getQuestionSource(instanceId, requestId)
+    const source = questionRegistry.getSource(instanceId, requestId)
 
     if (source === "legacy") {
       const workspace = sessionId ? await getOpenCodeWorkspaceIdForSession(instanceId, sessionId) : null
@@ -1219,7 +1689,7 @@ async function sendQuestionReject(instanceId: string, sessionId: string, request
 
   try {
     const client = getRootClient(instanceId)
-    const source = getQuestionSource(instanceId, requestId)
+    const source = questionRegistry.getSource(instanceId, requestId)
 
     if (source === "legacy") {
       const workspace = sessionId ? await getOpenCodeWorkspaceIdForSession(instanceId, sessionId) : null
@@ -1261,7 +1731,7 @@ async function sendPermissionResponse(
 
   try {
     const client = getRootClient(instanceId)
-    const source = getPermissionSource(instanceId, requestId)
+    const source = permissionRegistry.getSource(instanceId, requestId)
 
     if (source === "legacy") {
       const workspace = sessionId ? await getOpenCodeWorkspaceIdForSession(instanceId, sessionId) : null
@@ -1370,6 +1840,15 @@ export {
   updateInstance,
   removeInstance,
   createInstance,
+  cancelRestoreCreationRequest,
+  disposeRestoreCreatedInstance,
+  releaseRestoreCreatedInstance,
+  claimRestoreCreatedInstanceForUser,
+  waitForInitialWorkspaceLoad,
+  waitForInstanceReady,
+  waitForInstanceInitialHydration,
+  waitForInstanceInitialSessionHydration,
+  waitForInstanceWorkspaceMetadataHydration,
   getExistingInstanceForFolder,
   updateProjectNameForFolder,
   stopInstance,
@@ -1391,7 +1870,6 @@ export {
   markPermissionReplied,
   hasRepliedPermission,
   togglePermissionAutoAcceptForSession,
-  drainAutoAcceptPermissionsForInstance,
   clearPermissionQueue,
   sendPermissionResponse,
   setActivePermissionIdForInstance,
@@ -1411,4 +1889,6 @@ export {
   acknowledgeDisconnectedInstance,
   fetchLspStatus,
   disposeInstance,
+  reconcilePendingSessionIndicators,
+  clearReloadableInstanceState,
 }
diff --git a/packages/ui/src/stores/message-v2/bridge.ts b/packages/ui/src/stores/message-v2/bridge.ts
index 6ef773b7..44c3872a 100644
--- a/packages/ui/src/stores/message-v2/bridge.ts
+++ b/packages/ui/src/stores/message-v2/bridge.ts
@@ -5,6 +5,7 @@ import { getQuestionCallId, getQuestionMessageId } from "../../types/question"
 import type { Message, MessageInfo, ClientPart } from "../../types/message"
 import type { Session } from "../../types/session"
 import { messageStoreBus } from "./bus"
+import { canHydrateMessages } from "./message-hydration-authority"
 import type { MessageStatus, ReplaceMessageIdOptions, SessionRevertState } from "./types"
 
 interface SessionMetadata {
@@ -40,9 +41,11 @@ export function seedSessionMessagesV2(
   session: Session | SessionMetadata,
   messages: Message[],
   messageInfos?: Map<string, MessageInfo>,
-): void {
-  if (!session || !Array.isArray(messages)) return
+  expectedRevision?: number,
+): boolean {
+  if (!session || !Array.isArray(messages)) return false
   const store = messageStoreBus.getOrCreate(instanceId)
+  if (expectedRevision !== undefined && !canHydrateMessages(expectedRevision, store.getSessionRevision(session.id))) return false
   const metadata: SessionMetadata = "id" in session ? { id: session.id, title: session.title, parentId: session.parentId ?? null } : session
 
   store.addOrUpdateSession({
@@ -65,6 +68,7 @@ export function seedSessionMessagesV2(
   }))
 
   store.hydrateMessages(metadata.id, normalizedMessages, messageInfos?.values())
+  return true
 }
 
 interface MessageInfoOptions {
@@ -117,7 +121,7 @@ export function applyPartDeltaV2(
     partId: input.partId,
     field: input.field,
     delta: input.delta,
-    bumpSessionRevision: false,
+    bumpSessionRevision: true,
   })
 }
 
@@ -281,16 +285,16 @@ export function removePermissionV2(instanceId: string, permissionId: string): vo
   store.removePermission(permissionId)
 }
 
-export function removeMessageV2(instanceId: string, messageId: string): void {
+export function removeMessageV2(instanceId: string, messageId: string, sessionId?: string): void {
   if (!messageId) return
   const store = messageStoreBus.getOrCreate(instanceId)
-  store.removeMessage(messageId)
+  store.removeMessage(messageId, sessionId)
 }
 
-export function removeMessagePartV2(instanceId: string, messageId: string, partId: string): void {
+export function removeMessagePartV2(instanceId: string, messageId: string, partId: string, sessionId?: string): void {
   if (!messageId || !partId) return
   const store = messageStoreBus.getOrCreate(instanceId)
-  store.removeMessagePart(messageId, partId)
+  store.removeMessagePart(messageId, partId, sessionId)
 }
 
 export function ensureSessionMetadataV2(instanceId: string, session: Session | null | undefined): void {
diff --git a/packages/ui/src/stores/message-v2/bus.test.ts b/packages/ui/src/stores/message-v2/bus.test.ts
new file mode 100644
index 00000000..127b0d44
--- /dev/null
+++ b/packages/ui/src/stores/message-v2/bus.test.ts
@@ -0,0 +1,95 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { messageStoreBus } from "./bus.ts"
+import { invalidateSessionMessageLoad, messagesLoaded, setMessagesLoaded } from "../session-state.ts"
+
+describe("message store scroll snapshots", () => {
+  it("seeds an unregistered instance without claiming runtime authority", () => {
+    const instanceId = "session-restore-test"
+    const snapshot = {
+      scrollTop: 120,
+      scrollRatio: 0.5,
+      atBottom: false,
+      followModeType: "escaped" as const,
+      updatedAt: 1234,
+    }
+    const events: Array<{ instanceId: string; sessionId: string; scope: string; updatedAt: number }> = []
+    const stopListening = messageStoreBus.onScrollSnapshotChanged((id, sessionId, scope, value) => {
+      events.push({ instanceId: id, sessionId, scope, updatedAt: value.updatedAt })
+    })
+
+    try {
+      messageStoreBus.seedScrollSnapshots(instanceId, [
+        { sessionId: "session-1", scope: "message-stream", snapshot },
+      ])
+      const store = messageStoreBus.getOrCreate(instanceId)
+
+      assert.deepEqual(store.getScrollSnapshot("session-1", "message-stream"), snapshot)
+      assert.deepEqual(events, [])
+    } finally {
+      stopListening()
+      messageStoreBus.unregisterInstance(instanceId)
+    }
+  })
+
+  it("clears rehydrate values without publishing permanent instance removal", () => {
+    const instanceId = "scroll-rehydrate-cleanup"
+    const store = messageStoreBus.getOrCreate(instanceId)
+    let removals = 0
+    const stopListening = messageStoreBus.onInstanceDestroyed((id) => {
+      if (id === instanceId) removals += 1
+    })
+
+    try {
+      store.restoreScrollSnapshot("session-1", "message-stream", {
+        scrollTop: 80,
+        atBottom: false,
+        updatedAt: 1234,
+      })
+      messageStoreBus.clearInstanceScrollSnapshots(instanceId)
+
+      assert.equal(store.getScrollSnapshot("session-1", "message-stream"), undefined)
+      assert.equal(removals, 0)
+
+      messageStoreBus.unregisterInstance(instanceId)
+      assert.equal(removals, 1)
+    } finally {
+      stopListening()
+      if (messageStoreBus.getInstance(instanceId)) messageStoreBus.unregisterInstance(instanceId)
+    }
+  })
+
+  it("preserves scroll and invalidates message hydration during render-cache eviction", () => {
+    const instanceId = "scroll-render-cache-eviction"
+    const store = messageStoreBus.getOrCreate(instanceId)
+    const snapshot = { scrollTop: 240, atBottom: false, updatedAt: 2400 }
+    setMessagesLoaded((prev) => new Map(prev).set(instanceId, new Set(["session-1"])))
+    try {
+      store.restoreScrollSnapshot("session-1", "message-stream", snapshot)
+      invalidateSessionMessageLoad(instanceId, "session-1")
+      store.clearSession("session-1", { preserveScroll: true, notify: false })
+      assert.deepEqual(store.getScrollSnapshot("session-1", "message-stream"), snapshot)
+      assert.equal(messagesLoaded().get(instanceId)?.has("session-1") ?? false, false)
+    } finally {
+      messageStoreBus.unregisterInstance(instanceId)
+    }
+  })
+
+  it("does not replace newer runtime scroll with a late native seed", () => {
+    const instanceId = "scroll-late-seed"
+    const store = messageStoreBus.getOrCreate(instanceId)
+    const current = { scrollTop: 300, atBottom: false, updatedAt: 3000 }
+    try {
+      store.restoreScrollSnapshot("session-1", "message-stream", current)
+      messageStoreBus.seedScrollSnapshots(instanceId, [{
+        sessionId: "session-1",
+        scope: "message-stream",
+        snapshot: { scrollTop: 100, atBottom: false, updatedAt: 1000 },
+      }])
+      assert.deepEqual(store.getScrollSnapshot("session-1", "message-stream"), current)
+    } finally {
+      messageStoreBus.unregisterInstance(instanceId)
+    }
+  })
+})
diff --git a/packages/ui/src/stores/message-v2/bus.ts b/packages/ui/src/stores/message-v2/bus.ts
index 2115d7da..86900cd9 100644
--- a/packages/ui/src/stores/message-v2/bus.ts
+++ b/packages/ui/src/stores/message-v2/bus.ts
@@ -2,13 +2,24 @@ import { createInstanceMessageStore } from "./instance-store"
 import type { InstanceMessageStore } from "./instance-store"
 import { clearCacheForInstance } from "../../lib/global-cache"
 import { getLogger } from "../../lib/logger"
+import type { ScrollSnapshot } from "./types"
 
 const log = getLogger("session")
 
+export interface MessageScrollSnapshotSeed {
+  sessionId: string
+  scope: string
+  snapshot: ScrollSnapshot
+}
+
 class MessageStoreBus {
   private stores = new Map<string, InstanceMessageStore>()
   private teardownHandlers = new Set<(instanceId: string) => void>()
   private sessionClearHandlers = new Set<(instanceId: string, sessionId: string) => void>()
+  private scrollSnapshotHandlers = new Set<
+    (instanceId: string, sessionId: string, scope: string, snapshot: ScrollSnapshot) => void
+  >()
+  private scrollSnapshotSeeds = new Map<string, MessageScrollSnapshotSeed[]>()
 
   registerInstance(instanceId: string, store?: InstanceMessageStore): InstanceMessageStore {
     if (this.stores.has(instanceId)) {
@@ -19,8 +30,17 @@ class MessageStoreBus {
       store ??
       createInstanceMessageStore(instanceId, {
         onSessionCleared: (id, sessionId) => this.notifySessionCleared(id, sessionId),
+        onScrollSnapshotChanged: (id, sessionId, scope, snapshot) =>
+          this.notifyScrollSnapshotChanged(id, sessionId, scope, snapshot),
       })
     this.stores.set(instanceId, resolved)
+    const seeds = this.scrollSnapshotSeeds.get(instanceId)
+    if (seeds) {
+      this.scrollSnapshotSeeds.delete(instanceId)
+      for (const seed of seeds) {
+        this.applyScrollSeed(resolved, seed)
+      }
+    }
     return resolved
   }
 
@@ -41,6 +61,48 @@ class MessageStoreBus {
     }
   }
 
+  onScrollSnapshotChanged(
+    handler: (instanceId: string, sessionId: string, scope: string, snapshot: ScrollSnapshot) => void,
+  ): () => void {
+    this.scrollSnapshotHandlers.add(handler)
+    return () => {
+      this.scrollSnapshotHandlers.delete(handler)
+    }
+  }
+
+  seedScrollSnapshots(instanceId: string, seeds: MessageScrollSnapshotSeed[]): void {
+    if (seeds.length === 0) return
+    const store = this.stores.get(instanceId)
+    if (store) {
+      for (const seed of seeds) {
+        this.applyScrollSeed(store, seed)
+      }
+      return
+    }
+    this.scrollSnapshotSeeds.set(instanceId, seeds)
+  }
+
+  private applyScrollSeed(store: InstanceMessageStore, seed: MessageScrollSnapshotSeed): void {
+    const current = store.getScrollSnapshot(seed.sessionId, seed.scope)
+    if (current && current.updatedAt >= seed.snapshot.updatedAt) return
+    store.restoreScrollSnapshot(seed.sessionId, seed.scope, seed.snapshot)
+  }
+
+  private notifyScrollSnapshotChanged(
+    instanceId: string,
+    sessionId: string,
+    scope: string,
+    snapshot: ScrollSnapshot,
+  ): void {
+    for (const handler of this.scrollSnapshotHandlers) {
+      try {
+        handler(instanceId, sessionId, scope, snapshot)
+      } catch (error) {
+        log.error("Failed to run scroll snapshot change handler", error)
+      }
+    }
+  }
+
   getInstance(instanceId: string): InstanceMessageStore | undefined {
     return this.stores.get(instanceId)
   }
@@ -49,6 +111,11 @@ class MessageStoreBus {
     return this.registerInstance(instanceId)
   }
 
+  clearInstanceScrollSnapshots(instanceId: string): void {
+    this.stores.get(instanceId)?.clearScrollSnapshots()
+    this.scrollSnapshotSeeds.delete(instanceId)
+  }
+
   onInstanceDestroyed(handler: (instanceId: string) => void): () => void {
     this.teardownHandlers.add(handler)
     return () => {
@@ -64,6 +131,7 @@ class MessageStoreBus {
     clearCacheForInstance(instanceId)
     this.notifyInstanceDestroyed(instanceId)
     this.stores.delete(instanceId)
+    this.scrollSnapshotSeeds.delete(instanceId)
   }
 
   clearAll() {
@@ -72,7 +140,9 @@ class MessageStoreBus {
       clearCacheForInstance(instanceId)
       this.notifyInstanceDestroyed(instanceId)
       this.stores.delete(instanceId)
+      this.scrollSnapshotSeeds.delete(instanceId)
     }
+    this.scrollSnapshotSeeds.clear()
   }
 
   private notifyInstanceDestroyed(instanceId: string) {
diff --git a/packages/ui/src/stores/message-v2/instance-store.test.ts b/packages/ui/src/stores/message-v2/instance-store.test.ts
index 66a19516..975b4b9f 100644
--- a/packages/ui/src/stores/message-v2/instance-store.test.ts
+++ b/packages/ui/src/stores/message-v2/instance-store.test.ts
@@ -40,4 +40,5 @@ describe("message-v2 permission state", () => {
     assert.equal(store.state.permissions.active?.permission.id, "permission-2")
     assert.equal(store.getPermissionState(undefined, "permission-2")?.active, true)
   })
+
 })
diff --git a/packages/ui/src/stores/message-v2/instance-store.ts b/packages/ui/src/stores/message-v2/instance-store.ts
index 3ae5af56..437bea3d 100644
--- a/packages/ui/src/stores/message-v2/instance-store.ts
+++ b/packages/ui/src/stores/message-v2/instance-store.ts
@@ -13,6 +13,7 @@ import {
 import type { ClientPart, MessageInfo } from "../../types/message"
 import { mergePermissionRequest } from "../../types/permission"
 import { clearRecordDisplayCacheForMessages } from "./record-display-cache"
+import { mergePendingRequestEntry, shouldSkipPendingRequestUpsert } from "./pending-request-dedupe"
 import type {
   InstanceMessageState,
   LatestTodoSnapshot,
@@ -34,6 +35,7 @@ const storeLog = getLogger("session")
 
 interface MessageStoreHooks {
   onSessionCleared?: (instanceId: string, sessionId: string) => void
+  onScrollSnapshotChanged?: (instanceId: string, sessionId: string, scope: string, snapshot: ScrollSnapshot) => void
 }
 
 function createInitialState(instanceId: string): InstanceMessageState {
@@ -224,8 +226,8 @@ export interface InstanceMessageStore {
     bumpRevision?: boolean
     bumpSessionRevision: boolean
   }) => void
-  removeMessage: (messageId: string) => void
-  removeMessagePart: (messageId: string, partId: string) => void
+  removeMessage: (messageId: string, fallbackSessionId?: string) => void
+  removeMessagePart: (messageId: string, partId: string, fallbackSessionId?: string) => void
   bufferPendingPart: (entry: PendingPartEntry) => void
   flushPendingParts: (messageId: string) => void
   replaceMessageId: (options: ReplaceMessageIdOptions) => void
@@ -242,6 +244,7 @@ export interface InstanceMessageStore {
   rebuildUsage: (sessionId: string, infos: Iterable<MessageInfo>) => void
   getSessionUsage: (sessionId: string) => SessionUsageState | undefined
   setScrollSnapshot: (sessionId: string, scope: string, snapshot: Omit<ScrollSnapshot, "updatedAt">) => void
+  restoreScrollSnapshot: (sessionId: string, scope: string, snapshot: ScrollSnapshot) => void
   getScrollSnapshot: (sessionId: string, scope: string) => ScrollSnapshot | undefined
   getSessionRevision: (sessionId: string) => number
   getSessionMessageIds: (sessionId: string) => string[]
@@ -251,7 +254,8 @@ export interface InstanceMessageStore {
   getLastCompactionMessageIndex: (sessionId: string) => number
   getMessage: (messageId: string) => MessageRecord | undefined
   getLatestTodoSnapshot: (sessionId: string) => LatestTodoSnapshot | undefined
-  clearSession: (sessionId: string) => void
+  clearSession: (sessionId: string, options?: { preserveScroll?: boolean; notify?: boolean }) => void
+  clearScrollSnapshots: () => void
   clearInstance: () => void
 }
 
@@ -728,7 +732,7 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
     }
   }
 
-  function removeMessage(messageId: string) {
+  function removeMessage(messageId: string, fallbackSessionId?: string) {
     if (!messageId) return
 
     const record = state.messages[messageId]
@@ -747,6 +751,7 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
         }
       })
     }
+    if (!sessionIds.size && fallbackSessionId) sessionIds.add(fallbackSessionId)
 
     clearRecordDisplayCacheForMessages(instanceId, [messageId])
 
@@ -796,10 +801,13 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
     })
   }
 
-  function removeMessagePart(messageId: string, partId: string) {
+  function removeMessagePart(messageId: string, partId: string, fallbackSessionId?: string) {
     if (!messageId || !partId) return
     const message = state.messages[messageId]
-    if (!message) return
+    if (!message) {
+      if (fallbackSessionId) bumpSessionRevision(fallbackSessionId)
+      return
+    }
 
     clearRecordDisplayCacheForMessages(instanceId, [messageId])
 
@@ -958,6 +966,23 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
     const entry = mergePermissionEntry(input)
     const messageKey = entry.messageId ?? "__global__"
     const partKey = entry.partId ?? entry.permission?.id ?? "__global__"
+    const existing = state.permissions.queue.find((item) => item.permission.id === entry.permission.id)
+    const existingAtLocation = state.permissions.byMessage[messageKey]?.[partKey]
+    const expectedActiveId = state.permissions.queue[0]?.permission.id
+    if (shouldSkipPendingRequestUpsert({
+      existing,
+      existingAtLocationId: existingAtLocation?.permission.id,
+      expectedActiveId,
+      activeId: state.permissions.active?.permission.id,
+      incomingId: entry.permission.id,
+      incomingMessageId: entry.messageId,
+      incomingPartId: entry.partId,
+      incomingEnqueuedAt: entry.enqueuedAt,
+      existingValue: existing?.permission,
+      incomingValue: entry.permission,
+    })) {
+      return
+    }
 
     setState(
       "permissions",
@@ -1019,13 +1044,47 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
     return { entry, active }
   }
 
-  function upsertQuestion(entry: QuestionEntry) {
+  function mergeQuestionEntry(entry: QuestionEntry): QuestionEntry {
+    const existing = state.questions.queue.find((item) => item.request.id === entry.request.id)
+    return mergePendingRequestEntry(entry, existing)
+  }
+
+  function upsertQuestion(input: QuestionEntry) {
+    const entry = mergeQuestionEntry(input)
     const messageKey = entry.messageId ?? "__global__"
     const partKey = entry.partId ?? entry.request?.id ?? "__global__"
+    const existing = state.questions.queue.find((item) => item.request.id === entry.request.id)
+    const existingAtLocation = state.questions.byMessage[messageKey]?.[partKey]
+    const expectedActiveId = state.questions.queue[0]?.request.id
+    if (shouldSkipPendingRequestUpsert({
+      existing,
+      existingAtLocationId: existingAtLocation?.request.id,
+      expectedActiveId,
+      activeId: state.questions.active?.request.id,
+      incomingId: entry.request.id,
+      incomingMessageId: entry.messageId,
+      incomingPartId: entry.partId,
+      incomingEnqueuedAt: entry.enqueuedAt,
+      existingValue: existing?.request,
+      incomingValue: entry.request,
+    })) {
+      return
+    }
 
     setState(
       "questions",
       produce((draft) => {
+        Object.keys(draft.byMessage).forEach((existingMessageKey) => {
+          const partEntries = draft.byMessage[existingMessageKey]
+          Object.keys(partEntries).forEach((existingPartKey) => {
+            if (partEntries[existingPartKey].request.id === entry.request.id) {
+              delete partEntries[existingPartKey]
+            }
+          })
+          if (Object.keys(partEntries).length === 0) {
+            delete draft.byMessage[existingMessageKey]
+          }
+        })
         draft.byMessage[messageKey] = draft.byMessage[messageKey] ?? {}
         draft.byMessage[messageKey][partKey] = entry
         const existingIndex = draft.queue.findIndex((item) => item.request.id === entry.request.id)
@@ -1151,7 +1210,14 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
 
   function setScrollSnapshot(sessionId: string, scope: string, snapshot: Omit<ScrollSnapshot, "updatedAt">) {
     const key = makeScrollKey(sessionId, scope)
-    setState("scrollState", key, { ...snapshot, updatedAt: Date.now() })
+    const next = { ...snapshot, updatedAt: Date.now() }
+    setState("scrollState", key, next)
+    hooks?.onScrollSnapshotChanged?.(instanceId, sessionId, scope, next)
+  }
+
+  function restoreScrollSnapshot(sessionId: string, scope: string, snapshot: ScrollSnapshot) {
+    const key = makeScrollKey(sessionId, scope)
+    setState("scrollState", key, snapshot)
   }
 
   function getScrollSnapshot(sessionId: string, scope: string) {
@@ -1159,7 +1225,7 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
     return state.scrollState[key]
   }
 
-  function clearSession(sessionId: string) {
+  function clearSession(sessionId: string, options?: { preserveScroll?: boolean; notify?: boolean }) {
     if (!sessionId) return
 
     clearPromptDisplayOverridesForSession(instanceId, sessionId)
@@ -1228,16 +1294,18 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
         return next
       })
 
-      setState("scrollState", (prev) => {
-        const next = { ...prev }
-        const prefix = `${sessionId}:`
-        Object.keys(next).forEach((key) => {
-          if (key.startsWith(prefix)) {
-            delete next[key]
-          }
+      if (!options?.preserveScroll) {
+        setState("scrollState", (prev) => {
+          const next = { ...prev }
+          const prefix = `${sessionId}:`
+          Object.keys(next).forEach((key) => {
+            if (key.startsWith(prefix)) {
+              delete next[key]
+            }
+          })
+          return next
         })
-        return next
-      })
+      }
 
       setState("sessions", sessionId, (current) => {
         if (!current) return current
@@ -1255,7 +1323,7 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
 
     clearLatestTodoSnapshot(sessionId)
  
-    hooks?.onSessionCleared?.(instanceId, sessionId)
+    if (options?.notify !== false) hooks?.onSessionCleared?.(instanceId, sessionId)
   }
 
  
@@ -1264,6 +1332,10 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
      messageInfoCache.clear()
       setState(reconcile(createInitialState(instanceId)))
     }
+
+    function clearScrollSnapshots() {
+      setState("scrollState", reconcile({}))
+    }
  
     return {
 
@@ -1294,6 +1366,7 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
       rebuildUsage,
       getSessionUsage,
       setScrollSnapshot,
+      restoreScrollSnapshot,
       getScrollSnapshot,
       getSessionRevision: getSessionRevisionValue,
       getSessionMessageIds: (sessionId: string) => state.sessions[sessionId]?.messageIds ?? [],
@@ -1302,6 +1375,7 @@ export function createInstanceMessageStore(instanceId: string, hooks?: MessageSt
       getMessage: (messageId: string) => state.messages[messageId],
       getLatestTodoSnapshot: (sessionId: string) => state.latestTodos[sessionId],
       clearSession,
+      clearScrollSnapshots,
       clearInstance,
      }
    }
diff --git a/packages/ui/src/stores/message-v2/message-hydration-authority.test.ts b/packages/ui/src/stores/message-v2/message-hydration-authority.test.ts
new file mode 100644
index 00000000..d5ff9842
--- /dev/null
+++ b/packages/ui/src/stores/message-v2/message-hydration-authority.test.ts
@@ -0,0 +1,9 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import { canHydrateMessages } from "./message-hydration-authority.ts"
+
+test("rejects HTTP hydration after a newer message revision", () => {
+  assert.equal(canHydrateMessages(4, 5), false)
+  assert.equal(canHydrateMessages(5, 5), true)
+})
diff --git a/packages/ui/src/stores/message-v2/message-hydration-authority.ts b/packages/ui/src/stores/message-v2/message-hydration-authority.ts
new file mode 100644
index 00000000..c4493423
--- /dev/null
+++ b/packages/ui/src/stores/message-v2/message-hydration-authority.ts
@@ -0,0 +1,2 @@
+export const canHydrateMessages = (expectedRevision: number, currentRevision: number): boolean =>
+  expectedRevision === currentRevision
diff --git a/packages/ui/src/stores/message-v2/pending-request-dedupe.test.ts b/packages/ui/src/stores/message-v2/pending-request-dedupe.test.ts
new file mode 100644
index 00000000..37c27235
--- /dev/null
+++ b/packages/ui/src/stores/message-v2/pending-request-dedupe.test.ts
@@ -0,0 +1,57 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { mergePendingRequestEntry, shouldSkipPendingRequestUpsert } from "./pending-request-dedupe.ts"
+
+describe("pending request dedupe", () => {
+  it("skips unchanged polling updates at the same attachment location", () => {
+    const existing = {
+      messageId: "message-1",
+      partId: "part-1",
+      enqueuedAt: 1_000,
+    }
+    const request = { id: "question-1", sessionID: "session-1", questions: [{ header: "Confirm", question: "Continue?", options: [] }] }
+
+    assert.equal(shouldSkipPendingRequestUpsert({
+      existing,
+      existingAtLocationId: "question-1",
+      expectedActiveId: "question-1",
+      activeId: "question-1",
+      incomingId: "question-1",
+      incomingMessageId: "message-1",
+      incomingPartId: "part-1",
+      incomingEnqueuedAt: 1_000,
+      existingValue: request,
+      incomingValue: { ...request, questions: [...request.questions] },
+    }), true)
+  })
+
+  it("does not skip when polling resolves a request from global state to a tool part", () => {
+    const existing = {
+      enqueuedAt: 1_000,
+    }
+    const request = { id: "question-1", sessionID: "session-1", questions: [{ header: "Confirm", question: "Continue?", options: [] }] }
+
+    assert.equal(shouldSkipPendingRequestUpsert({
+      existing,
+      existingAtLocationId: undefined,
+      expectedActiveId: "question-1",
+      activeId: "question-1",
+      incomingId: "question-1",
+      incomingMessageId: "message-1",
+      incomingPartId: "part-1",
+      incomingEnqueuedAt: 1_000,
+      existingValue: request,
+      incomingValue: request,
+    }), false)
+  })
+
+  it("keeps the earliest queue time while preserving resolved attachment ids", () => {
+    const merged = mergePendingRequestEntry(
+      { messageId: "message-1", partId: "part-1", enqueuedAt: 3_000 },
+      { enqueuedAt: 1_000 },
+    )
+
+    assert.deepEqual(merged, { messageId: "message-1", partId: "part-1", enqueuedAt: 1_000 })
+  })
+})
diff --git a/packages/ui/src/stores/message-v2/pending-request-dedupe.ts b/packages/ui/src/stores/message-v2/pending-request-dedupe.ts
new file mode 100644
index 00000000..fa96e8d7
--- /dev/null
+++ b/packages/ui/src/stores/message-v2/pending-request-dedupe.ts
@@ -0,0 +1,50 @@
+export interface PendingRequestEntryLike {
+  messageId?: string
+  partId?: string
+  enqueuedAt: number
+}
+
+export interface PendingRequestSkipInput {
+  existing: PendingRequestEntryLike | undefined
+  existingAtLocationId: string | undefined
+  expectedActiveId: string | undefined
+  activeId: string | undefined
+  incomingId: string
+  incomingMessageId: string | undefined
+  incomingPartId: string | undefined
+  incomingEnqueuedAt: number
+  existingValue: unknown
+  incomingValue: unknown
+}
+
+export function areStructuredValuesEqual(left: unknown, right: unknown): boolean {
+  if (left === right) return true
+  try {
+    return JSON.stringify(left) === JSON.stringify(right)
+  } catch {
+    return false
+  }
+}
+
+export function mergePendingRequestEntry<T extends PendingRequestEntryLike>(entry: T, existing: T | undefined): T {
+  if (!existing) return entry
+  return {
+    ...entry,
+    messageId: entry.messageId ?? existing.messageId,
+    partId: entry.partId ?? existing.partId,
+    enqueuedAt: Math.min(existing.enqueuedAt, entry.enqueuedAt),
+  }
+}
+
+export function shouldSkipPendingRequestUpsert(input: PendingRequestSkipInput): boolean {
+  const existing = input.existing
+  return Boolean(
+    existing &&
+    input.existingAtLocationId === input.incomingId &&
+    input.activeId === input.expectedActiveId &&
+    existing.messageId === input.incomingMessageId &&
+    existing.partId === input.incomingPartId &&
+    existing.enqueuedAt === input.incomingEnqueuedAt &&
+    areStructuredValuesEqual(input.existingValue, input.incomingValue),
+  )
+}
diff --git a/packages/ui/src/stores/message-v2/types.ts b/packages/ui/src/stores/message-v2/types.ts
index 6e2279c9..b49fbf00 100644
--- a/packages/ui/src/stores/message-v2/types.ts
+++ b/packages/ui/src/stores/message-v2/types.ts
@@ -82,9 +82,7 @@ export interface ScrollSnapshot {
   anchorKey?: string
   anchorOffset?: number
   atBottom: boolean
-  followModeType?: "following" | "escaped" | "holding"
-  heldKey?: string
-  holdAnchorSuspended?: boolean
+  followModeType?: "following" | "escaped"
   updatedAt: number
 }
 
diff --git a/packages/ui/src/stores/opencode-workspaces.ts b/packages/ui/src/stores/opencode-workspaces.ts
index 419161dc..b6829583 100644
--- a/packages/ui/src/stores/opencode-workspaces.ts
+++ b/packages/ui/src/stores/opencode-workspaces.ts
@@ -3,6 +3,24 @@ import { getWorktreeSlugForSession, getWorktrees } from "./worktrees"
 import { getLogger } from "../lib/logger"
 import { mapOpenCodeWorkspacesToWorktreeSlugs } from "./opencode-workspace-matching"
 
+const WORKSPACE_SYNC_TIMEOUT_MS = 5_000
+
+function withWorkspaceSyncTimeout<T>(operation: Promise<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("OpenCode workspace sync timed out")), WORKSPACE_SYNC_TIMEOUT_MS)
+    operation.then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (error) => {
+        clearTimeout(timer)
+        reject(error)
+      },
+    )
+  })
+}
+
 const log = getLogger("api")
 
 type OpenCodeWorkspace = {
@@ -48,8 +66,8 @@ async function syncOpenCodeWorkspaces(instanceId: string): Promise<void> {
       return
     }
 
-    await workspaceApi.syncList({ directory: instance.folder })
-    const result = await workspaceApi.list({ directory: instance.folder })
+    await withWorkspaceSyncTimeout(workspaceApi.syncList({ directory: instance.folder }))
+    const result = await withWorkspaceSyncTimeout<any>(workspaceApi.list({ directory: instance.folder }))
     const workspaces = Array.isArray(result?.data) ? (result.data as OpenCodeWorkspace[]) : []
     const next = mapOpenCodeWorkspacesToWorktreeSlugs(getWorktrees(instanceId), workspaces)
 
@@ -57,10 +75,14 @@ async function syncOpenCodeWorkspaces(instanceId: string): Promise<void> {
   })()
     .catch((error) => {
       log.warn("Failed to sync OpenCode workspaces", { instanceId, error })
-      workspaceIdByWorktreeSlug.set(instanceId, new Map())
+      if (!workspaceIdByWorktreeSlug.has(instanceId)) {
+        workspaceIdByWorktreeSlug.set(instanceId, new Map())
+      }
     })
     .finally(() => {
-      workspaceSyncs.delete(instanceId)
+      if (workspaceSyncs.get(instanceId) === task) {
+        workspaceSyncs.delete(instanceId)
+      }
     })
 
   workspaceSyncs.set(instanceId, task)
@@ -68,7 +90,7 @@ async function syncOpenCodeWorkspaces(instanceId: string): Promise<void> {
 }
 
 async function reloadOpenCodeWorkspaces(instanceId: string): Promise<void> {
-  workspaceSyncs.delete(instanceId)
+  await workspaceSyncs.get(instanceId)
   await syncOpenCodeWorkspaces(instanceId)
 }
 
diff --git a/packages/ui/src/stores/permission-auto-accept.ts b/packages/ui/src/stores/permission-auto-accept.ts
index aca94793..f991186b 100644
--- a/packages/ui/src/stores/permission-auto-accept.ts
+++ b/packages/ui/src/stores/permission-auto-accept.ts
@@ -1,15 +1,28 @@
 import { createSignal } from "solid-js"
-import type { PermissionReply, PermissionRequest } from "../types/permission"
-import { getPermissionSessionId } from "../types/permission"
-import { getLogger } from "../lib/logger"
 
-const STORAGE_KEY = "codenomad:permission-auto-accept:v1"
+/**
+ * UI-side mirror of the server-owned Yolo (permission auto-accept) state.
+ *
+ * The server is authoritative: it holds the toggle state, resolves
+ * family-root inheritance, and performs the actual `"once"` replies. This
+ * module only keeps a runtime (NON-persisted) projection so the UI can render
+ * the badge / switch synchronously.
+ *
+ * State is populated from:
+ *   - local toggles (optimistic, then confirmed via REST)
+ *   - `yolo.stateChanged` SSE events (wired in the app bootstrap, see
+ *     `stores/instances.ts`, so toggles from other clients reflect)
+ *
+ * `resolvePermissionAutoAcceptFamilyRoot` is retained as a display aid so the
+ * badge correctly lights up for child/sub-sessions of an enabled family root,
+ * preserving the previous inheritance UX exactly. The server performs the same
+ * resolution independently when deciding whether to auto-reply.
+ *
+ * NOTE: intentionally pure — no SSE/REST side effects at module load, so it
+ * stays unit-testable.
+ */
 
-const log = getLogger("api")
-
-type AutoAcceptResponder = (instanceId: string, sessionId: string, requestId: string, reply: PermissionReply) => Promise<void>
-type PendingPermissionChecker = (instanceId: string, requestId: string) => boolean
-type PermissionAutoAcceptSession = {
+export type PermissionAutoAcceptSession = {
   id: string
   parentId?: string | null
   revert?: unknown
@@ -45,112 +58,44 @@ function makeKey(instanceId: string, sessionId: string) {
   return `${instanceId}:${resolveFamilyRoot(instanceId, sessionId)}`
 }
 
-function readInitialState() {
-  if (typeof window === "undefined" || !window.localStorage) {
-    return new Map<string, boolean>()
-  }
-
-  try {
-    const raw = window.localStorage.getItem(STORAGE_KEY)
-    if (!raw) return new Map<string, boolean>()
-    const parsed = JSON.parse(raw) as Record<string, boolean>
-    return new Map(Object.entries(parsed).filter((entry): entry is [string, boolean] => entry[1] === true))
-  } catch {
-    return new Map<string, boolean>()
-  }
-}
-
-function persist(next: Map<string, boolean>) {
-  if (typeof window === "undefined" || !window.localStorage) {
-    return
-  }
-
-  try {
-    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(Object.fromEntries(next)))
-  } catch {
-    // ignore persistence failures
-  }
-}
-
-const [autoAcceptState, setAutoAcceptState] = createSignal(readInitialState())
-
-const inFlight = new Set<string>()
+const [autoAcceptState, setAutoAcceptState] = createSignal<Map<string, boolean>>(new Map())
 
 export function isPermissionAutoAcceptEnabled(instanceId: string, sessionId: string) {
   return autoAcceptState().get(makeKey(instanceId, sessionId)) ?? false
 }
 
 export function setPermissionAutoAcceptEnabled(instanceId: string, sessionId: string, enabled: boolean) {
-  const key = makeKey(instanceId, sessionId)
   setAutoAcceptState((prev) => {
+    const key = makeKey(instanceId, sessionId)
+    if (prev.get(key) === enabled) return prev
     const next = new Map(prev)
     if (enabled) {
       next.set(key, true)
     } else {
       next.delete(key)
     }
-    persist(next)
     return next
   })
-  if (!enabled) {
-    clearAutoAcceptSession(instanceId, sessionId)
-  }
 }
 
 export function togglePermissionAutoAccept(instanceId: string, sessionId: string) {
-  setPermissionAutoAcceptEnabled(instanceId, sessionId, !isPermissionAutoAcceptEnabled(instanceId, sessionId))
+  const next = !isPermissionAutoAcceptEnabled(instanceId, sessionId)
+  setPermissionAutoAcceptEnabled(instanceId, sessionId, next)
+  return next
 }
 
-function makeRequestKey(instanceId: string, sessionId: string, requestId: string) {
-  return `${makeKey(instanceId, sessionId)}:${requestId}`
-}
-
-export function clearAutoAcceptPermission(instanceId: string, sessionId: string, requestId: string) {
-  const requestKey = makeRequestKey(instanceId, sessionId, requestId)
-  inFlight.delete(requestKey)
-}
-
-export function clearAutoAcceptSession(instanceId: string, sessionId: string) {
-  const prefix = `${makeKey(instanceId, sessionId)}:`
-  for (const requestKey of Array.from(inFlight)) {
-    if (requestKey.startsWith(prefix)) {
-      inFlight.delete(requestKey)
+/** Remove all Yolo state entries for an instance (workspace stop / removal). */
+export function clearPermissionAutoAcceptForInstance(instanceId: string) {
+  setAutoAcceptState((prev) => {
+    const prefix = `${instanceId}:`
+    let changed = false
+    const next = new Map(prev)
+    for (const key of Array.from(next.keys())) {
+      if (key.startsWith(prefix)) {
+        next.delete(key)
+        changed = true
+      }
     }
-  }
-}
-
-export function drainAutoAcceptPermission(
-  instanceId: string,
-  permission: PermissionRequest,
-  responder: AutoAcceptResponder,
-  isPending: PendingPermissionChecker,
-) {
-  const sessionId = getPermissionSessionId(permission)
-  if (!sessionId || !permission?.id) return
-  if (!isPermissionAutoAcceptEnabled(instanceId, sessionId)) return
-  if (!isPending(instanceId, permission.id)) return
-
-  const requestKey = makeRequestKey(instanceId, sessionId, permission.id)
-  if (inFlight.has(requestKey)) return
-
-  inFlight.add(requestKey)
-
-  void responder(instanceId, sessionId, permission.id, "once")
-    .catch((error) => {
-      log.error("Failed to auto-accept permission", error)
-    })
-    .finally(() => {
-      inFlight.delete(requestKey)
-    })
-}
-
-export function drainAutoAcceptPermissions(
-  instanceId: string,
-  permissions: PermissionRequest[],
-  responder: AutoAcceptResponder,
-  isPending: PendingPermissionChecker,
-) {
-  for (const permission of permissions) {
-    drainAutoAcceptPermission(instanceId, permission, responder, isPending)
-  }
+    return changed ? next : prev
+  })
 }
diff --git a/packages/ui/src/stores/permission-lifecycle.test.ts b/packages/ui/src/stores/permission-lifecycle.test.ts
new file mode 100644
index 00000000..15520d80
--- /dev/null
+++ b/packages/ui/src/stores/permission-lifecycle.test.ts
@@ -0,0 +1,96 @@
+import assert from "node:assert/strict"
+import { afterEach, test } from "node:test"
+import type { OpencodeClient } from "@opencode-ai/sdk/v2/client"
+import { sdkManager } from "../lib/sdk-manager"
+import type { Instance } from "../types/instance"
+import {
+  addInstance,
+  clearPermissionQueue,
+  getPermissionQueue,
+  sendPermissionResponse,
+} from "./instances"
+import { messageStoreBus } from "./message-v2/bus"
+import { handlePermissionUpdated } from "./session-events"
+
+const instanceIds: string[] = []
+const originalCreateClient = sdkManager.createClient
+
+function addTestInstance(id: string, client: OpencodeClient): void {
+  instanceIds.push(id)
+  addInstance({
+    id,
+    folder: "/workspace",
+    port: 1,
+    pid: 1,
+    proxyPath: `/workspaces/${id}/instance`,
+    status: "ready",
+    client,
+  } satisfies Instance)
+}
+
+afterEach(() => {
+  for (const instanceId of instanceIds.splice(0)) {
+    clearPermissionQueue(instanceId)
+    messageStoreBus.unregisterInstance(instanceId)
+    sdkManager.destroyClientsForInstance(instanceId)
+  }
+  sdkManager.createClient = originalCreateClient
+})
+
+test("permission.updated preserves the V2 reply route", async () => {
+  let legacyReplies = 0
+  let v2Replies = 0
+  const client = {
+    permission: {
+      reply: async () => { legacyReplies += 1; return { data: true } },
+    },
+    v2: { session: { permission: {
+      reply: async () => { v2Replies += 1; return { data: true } },
+    } } },
+  } as unknown as OpencodeClient
+  sdkManager.createClient = (() => client) as typeof sdkManager.createClient
+  addTestInstance("permission-v2-source", client)
+
+  handlePermissionUpdated("permission-v2-source", {
+    type: "permission.v2.asked",
+    properties: { id: "permission", sessionID: "session", action: "external_directory", resources: ["C:/work"] },
+  } as never)
+  handlePermissionUpdated("permission-v2-source", {
+    type: "permission.updated",
+    properties: { id: "permission", sessionID: "session", patterns: ["C:/work"] },
+  })
+  await sendPermissionResponse("permission-v2-source", "session", "permission", "always")
+
+  assert.equal(v2Replies, 1)
+  assert.equal(legacyReplies, 0)
+  handlePermissionUpdated("permission-v2-source", {
+    type: "permission.updated",
+    properties: { id: "permission", sessionID: "session", patterns: ["C:/work"] },
+  })
+  assert.deepEqual(getPermissionQueue("permission-v2-source"), [])
+})
+
+test("standalone permission.updated remains a legacy permission request", async () => {
+  let legacyReplies = 0
+  let v2Replies = 0
+  const client = {
+    permission: {
+      reply: async () => { legacyReplies += 1; return { data: true } },
+    },
+    v2: { session: { permission: {
+      reply: async () => { v2Replies += 1; return { data: true } },
+    } } },
+  } as unknown as OpencodeClient
+  sdkManager.createClient = (() => client) as typeof sdkManager.createClient
+  addTestInstance("permission-legacy-update", client)
+
+  handlePermissionUpdated("permission-legacy-update", {
+    type: "permission.updated",
+    properties: { id: "permission", sessionID: "session", patterns: ["C:/work"] },
+  })
+  assert.equal(getPermissionQueue("permission-legacy-update").length, 1)
+  await sendPermissionResponse("permission-legacy-update", "session", "permission", "always")
+
+  assert.equal(legacyReplies, 1)
+  assert.equal(v2Replies, 0)
+})
diff --git a/packages/ui/src/stores/preferences.test.ts b/packages/ui/src/stores/preferences.test.ts
new file mode 100644
index 00000000..bc6601b5
--- /dev/null
+++ b/packages/ui/src/stores/preferences.test.ts
@@ -0,0 +1,120 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { buildSpeechPatch } from "../lib/speech-patch"
+import type { SpeechSettingsUpdate } from "./preferences"
+
+describe("buildSpeechPatch", () => {
+  it("only includes fields that are explicitly provided", () => {
+    const patch = buildSpeechPatch({ ttsVoice: "alloy" })
+    assert.deepEqual(patch, { ttsVoice: "alloy" })
+  })
+
+  it("does not include fields that were not provided", () => {
+    const patch = buildSpeechPatch({ separateProviders: true })
+    assert.deepEqual(patch, { separateProviders: true })
+    assert.equal("apiKey" in patch, false)
+    assert.equal("baseUrl" in patch, false)
+    assert.equal("sttModel" in patch, false)
+    assert.equal("stt" in patch, false)
+    assert.equal("tts" in patch, false)
+  })
+
+  it("converts empty string shared baseUrl to null", () => {
+    const patch = buildSpeechPatch({ baseUrl: "  " })
+    assert.equal(patch.baseUrl, null)
+  })
+
+  it("preserves non-empty shared baseUrl", () => {
+    const patch = buildSpeechPatch({ baseUrl: "  https://api.openai.com/v1  " })
+    assert.equal(patch.baseUrl, "https://api.openai.com/v1")
+  })
+
+  it("clears shared apiKey with null", () => {
+    const patch = buildSpeechPatch({ apiKey: null })
+    assert.equal(patch.apiKey, null)
+  })
+
+  it("sets shared apiKey to provided value", () => {
+    const patch = buildSpeechPatch({ apiKey: "sk-new" })
+    assert.equal(patch.apiKey, "sk-new")
+  })
+
+  it("includes directional apiKey as null for clearing", () => {
+    const patch = buildSpeechPatch({ stt: { apiKey: null } })
+    assert.deepEqual(patch.stt, { apiKey: null })
+  })
+
+  it("includes directional apiKey as string for setting", () => {
+    const patch = buildSpeechPatch({ stt: { apiKey: "sk-groq" } })
+    assert.deepEqual(patch.stt, { apiKey: "sk-groq" })
+  })
+
+  it("includes directional baseUrl only when provided", () => {
+    const patch = buildSpeechPatch({ stt: { baseUrl: "https://api.groq.com/openai/v1" } })
+    assert.deepEqual(patch.stt, { baseUrl: "https://api.groq.com/openai/v1" })
+  })
+
+  it("converts empty directional baseUrl to null", () => {
+    const patch = buildSpeechPatch({ stt: { baseUrl: "" } })
+    assert.deepEqual(patch.stt, { baseUrl: null })
+  })
+
+  it("clears all directional fields", () => {
+    const patch = buildSpeechPatch({
+      stt: { apiKey: null, baseUrl: null, model: null },
+      tts: { apiKey: null, baseUrl: null, model: null },
+    })
+    assert.deepEqual(patch.stt, { apiKey: null, baseUrl: null, model: null })
+    assert.deepEqual(patch.tts, { apiKey: null, baseUrl: null, model: null })
+  })
+
+  it("includes complete directional pair", () => {
+    const patch = buildSpeechPatch({
+      stt: { apiKey: "sk-groq", baseUrl: "https://api.groq.com/openai/v1", model: "whisper-large-v3" },
+    })
+    assert.deepEqual(patch.stt, {
+      apiKey: "sk-groq",
+      baseUrl: "https://api.groq.com/openai/v1",
+      model: "whisper-large-v3",
+    })
+  })
+
+  it("does not include empty directional sub-objects", () => {
+    const patch = buildSpeechPatch({ stt: {}, tts: {} })
+    assert.equal("stt" in patch, false)
+    assert.equal("tts" in patch, false)
+  })
+
+  it("trims directional model and converts empty to null", () => {
+    const patch = buildSpeechPatch({ stt: { model: "  whisper-large-v3  " } })
+    assert.equal((patch.stt as Record<string, unknown>).model, "whisper-large-v3")
+
+    const patchEmpty = buildSpeechPatch({ stt: { model: "  " } })
+    assert.equal((patchEmpty.stt as Record<string, unknown>).model, null)
+  })
+
+  it("does not materialize fallback values from current settings", () => {
+    const patch = buildSpeechPatch({ ttsVoice: "nova" })
+    assert.equal("stt" in patch, false, "should not materialize stt sub-object")
+    assert.equal("tts" in patch, false, "should not materialize tts sub-object")
+    assert.equal("sttModel" in patch, false, "should not materialize sttModel")
+    assert.equal("ttsModel" in patch, false, "should not materialize ttsModel")
+    assert.equal("playbackMode" in patch, false, "should not materialize playbackMode")
+  })
+
+  it("builds a minimal patch for mode switch only", () => {
+    const patch = buildSpeechPatch({ separateProviders: false })
+    assert.deepEqual(patch, { separateProviders: false })
+  })
+
+  it("builds a mode switch with directional cleanup", () => {
+    const patch = buildSpeechPatch({
+      separateProviders: false,
+      stt: { apiKey: null, baseUrl: null, model: null },
+      tts: { apiKey: null, baseUrl: null, model: null },
+    })
+    assert.equal(patch.separateProviders, false)
+    assert.deepEqual(patch.stt, { apiKey: null, baseUrl: null, model: null })
+    assert.deepEqual(patch.tts, { apiKey: null, baseUrl: null, model: null })
+  })
+})
diff --git a/packages/ui/src/stores/preferences.tsx b/packages/ui/src/stores/preferences.tsx
index e3fde894..2f39824b 100644
--- a/packages/ui/src/stores/preferences.tsx
+++ b/packages/ui/src/stores/preferences.tsx
@@ -13,6 +13,7 @@ import {
 } from "./instance-config"
 import { getLogger } from "../lib/logger"
 import { loadSpeechCapabilities, resetSpeechCapabilities } from "./speech"
+import { buildSpeechPatch } from "../lib/speech-patch"
 
 const log = getLogger("actions")
 
@@ -31,9 +32,10 @@ export interface ModelPreference {
 
 export type DiffViewMode = "split" | "unified"
 export type ExpansionPreference = "expanded" | "collapsed"
+export type VisibilityPreference = "hidden" | ExpansionPreference
 export type ToolCallExpansionPreset = "minimal" | "balanced" | "detailed" | "everything"
 export type ToolCallExpansionPresetSelection = ToolCallExpansionPreset | "custom"
-export type ToolInputsVisibilityPreference = "hidden" | "collapsed" | "expanded"
+export type ToolInputsVisibilityPreference = VisibilityPreference
 export type ListeningMode = "local" | "all"
 export type ServerLogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR"
 export type SpeechProviderPreference = "openai-compatible"
@@ -43,7 +45,7 @@ export type SpeechTtsFormat = "mp3" | "wav" | "opus" | "aac"
 export interface ToolCallExpansionDefaults {
   preset: ToolCallExpansionPresetSelection
   thinking: ExpansionPreference
-  tools: Record<string, ExpansionPreference>
+  tools: Record<string, VisibilityPreference>
 }
 
 export interface SpeechSettings {
@@ -56,10 +58,30 @@ export interface SpeechSettings {
   ttsVoice: string
   playbackMode: SpeechPlaybackMode
   ttsFormat: SpeechTtsFormat
+  separateProviders: boolean
+  stt: {
+    apiKey?: string
+    hasApiKey: boolean
+    baseUrl?: string
+    model: string
+  }
+  tts: {
+    apiKey?: string
+    hasApiKey: boolean
+    baseUrl?: string
+    model: string
+  }
 }
 
-export type SpeechSettingsUpdate = Partial<Omit<SpeechSettings, "apiKey">> & {
+export type SpeechSettingsUpdate = Partial<Omit<SpeechSettings, "provider" | "hasApiKey" | "apiKey" | "baseUrl" | "sttModel" | "ttsModel" | "ttsVoice" | "stt" | "tts">> & {
   apiKey?: string | null
+  baseUrl?: string | null
+  sttModel?: string | null
+  ttsModel?: string | null
+  ttsVoice?: string | null
+  separateProviders?: boolean
+  stt?: { apiKey?: string | null; baseUrl?: string | null; model?: string | null }
+  tts?: { apiKey?: string | null; baseUrl?: string | null; model?: string | null }
 }
 
 export interface UiSettings {
@@ -75,9 +97,10 @@ export interface UiSettings {
   diffViewMode: DiffViewMode
   toolCallExpansionDefaults: ToolCallExpansionDefaults
   toolOutputExpansion: ExpansionPreference
-  diagnosticsExpansion: ExpansionPreference
+  diagnosticsExpansion: VisibilityPreference
   toolInputsVisibility: ToolInputsVisibilityPreference
   showUsageMetrics: boolean
+  usageMetricsExpansion: ExpansionPreference
   autoCleanupBlankSessions: boolean
   keepUnseenSubagentIdleStatus: boolean
 
@@ -167,6 +190,7 @@ const defaultUiSettings: UiSettings = {
   diagnosticsExpansion: "expanded",
   toolInputsVisibility: "collapsed",
   showUsageMetrics: true,
+  usageMetricsExpansion: "collapsed",
   autoCleanupBlankSessions: true,
   keepUnseenSubagentIdleStatus: false,
 
@@ -180,6 +204,10 @@ function normalizeExpansionPreference(value: unknown, fallback: ExpansionPrefere
   return value === "expanded" || value === "collapsed" ? value : fallback
 }
 
+function normalizeVisibilityPreference(value: unknown, fallback: VisibilityPreference): VisibilityPreference {
+  return value === "hidden" || value === "expanded" || value === "collapsed" ? value : fallback
+}
+
 function normalizeToolCallExpansionPreset(value: unknown): ToolCallExpansionPresetSelection {
   if (value === "minimal" || value === "balanced" || value === "detailed" || value === "everything" || value === "custom") {
     return value
@@ -187,12 +215,12 @@ function normalizeToolCallExpansionPreset(value: unknown): ToolCallExpansionPres
   return defaultToolCallExpansionDefaults.preset
 }
 
-function normalizeToolCallExpansionTools(value: unknown): Record<string, ExpansionPreference> {
+function normalizeToolCallExpansionTools(value: unknown): Record<string, VisibilityPreference> {
   if (!value || typeof value !== "object" || Array.isArray(value)) return {}
-  const next: Record<string, ExpansionPreference> = {}
+  const next: Record<string, VisibilityPreference> = {}
   for (const [tool, mode] of Object.entries(value as Record<string, unknown>)) {
     if (!tool) continue
-    if (mode === "expanded" || mode === "collapsed") {
+    if (mode === "hidden" || mode === "expanded" || mode === "collapsed") {
       next[tool] = mode
     }
   }
@@ -205,7 +233,7 @@ function normalizeToolCallExpansionDefaults(input: unknown, legacySettings: Part
     : undefined
   const legacyThinking = normalizeExpansionPreference(
     legacySettings.thinkingBlocksExpansion,
-    defaultToolCallExpansionDefaults.thinking,
+    "collapsed",
   )
 
   return {
@@ -223,10 +251,24 @@ const defaultSpeechSettings: SpeechSettings = {
   ttsVoice: "alloy",
   playbackMode: "streaming",
   ttsFormat: "mp3",
+  separateProviders: false,
+  stt: {
+    hasApiKey: false,
+    model: "gpt-4o-mini-transcribe",
+  },
+  tts: {
+    hasApiKey: false,
+    model: "gpt-4o-mini-tts",
+  },
 }
 
 function normalizeUiSettings(input?: Partial<UiSettings> | null): UiSettings {
   const sanitized = input ?? {}
+  const toolCallExpansionDefaults = normalizeToolCallExpansionDefaults(sanitized.toolCallExpansionDefaults, sanitized)
+  const usageMetricsFallback =
+    toolCallExpansionDefaults.preset === "minimal" || toolCallExpansionDefaults.preset === "balanced"
+      ? "collapsed"
+      : "expanded"
   return {
     showThinkingBlocks: sanitized.showThinkingBlocks ?? defaultUiSettings.showThinkingBlocks,
     showKeyboardShortcutHints:
@@ -239,14 +281,21 @@ function normalizeUiSettings(input?: Partial<UiSettings> | null): UiSettings {
     showPromptVoiceInput: sanitized.showPromptVoiceInput ?? defaultUiSettings.showPromptVoiceInput,
     locale: sanitized.locale ?? defaultUiSettings.locale,
     diffViewMode: sanitized.diffViewMode ?? defaultUiSettings.diffViewMode,
-    toolCallExpansionDefaults: normalizeToolCallExpansionDefaults(sanitized.toolCallExpansionDefaults, sanitized),
+    toolCallExpansionDefaults,
     toolOutputExpansion: sanitized.toolOutputExpansion ?? defaultUiSettings.toolOutputExpansion,
-    diagnosticsExpansion: sanitized.diagnosticsExpansion ?? defaultUiSettings.diagnosticsExpansion,
+    diagnosticsExpansion: normalizeVisibilityPreference(
+      sanitized.diagnosticsExpansion,
+      defaultUiSettings.diagnosticsExpansion,
+    ),
     toolInputsVisibility:
       sanitized.toolInputsVisibility === "hidden" || sanitized.toolInputsVisibility === "collapsed" || sanitized.toolInputsVisibility === "expanded"
         ? sanitized.toolInputsVisibility
         : defaultUiSettings.toolInputsVisibility,
     showUsageMetrics: sanitized.showUsageMetrics ?? defaultUiSettings.showUsageMetrics,
+    usageMetricsExpansion: normalizeExpansionPreference(
+      sanitized.usageMetricsExpansion,
+      usageMetricsFallback,
+    ),
     autoCleanupBlankSessions: sanitized.autoCleanupBlankSessions ?? defaultUiSettings.autoCleanupBlankSessions,
     keepUnseenSubagentIdleStatus:
       sanitized.keepUnseenSubagentIdleStatus ?? defaultUiSettings.keepUnseenSubagentIdleStatus,
@@ -269,19 +318,21 @@ function normalizeRecord(value: unknown): Record<string, string> {
 
 function normalizeSpeechSettings(input?: Partial<SpeechSettings> | null): SpeechSettings {
   const sanitized = input ?? {}
+  const sttModel =
+    typeof sanitized.sttModel === "string" && sanitized.sttModel.trim()
+      ? sanitized.sttModel.trim()
+      : defaultSpeechSettings.sttModel
+  const ttsModel =
+    typeof sanitized.ttsModel === "string" && sanitized.ttsModel.trim()
+      ? sanitized.ttsModel.trim()
+      : defaultSpeechSettings.ttsModel
   return {
     provider: sanitized.provider === "openai-compatible" ? sanitized.provider : defaultSpeechSettings.provider,
     apiKey: typeof sanitized.apiKey === "string" && sanitized.apiKey.trim() ? sanitized.apiKey.trim() : undefined,
     hasApiKey: sanitized.hasApiKey === true || (typeof sanitized.apiKey === "string" && sanitized.apiKey.trim().length > 0),
     baseUrl: typeof sanitized.baseUrl === "string" && sanitized.baseUrl.trim() ? sanitized.baseUrl.trim() : undefined,
-    sttModel:
-      typeof sanitized.sttModel === "string" && sanitized.sttModel.trim()
-        ? sanitized.sttModel.trim()
-        : defaultSpeechSettings.sttModel,
-    ttsModel:
-      typeof sanitized.ttsModel === "string" && sanitized.ttsModel.trim()
-        ? sanitized.ttsModel.trim()
-        : defaultSpeechSettings.ttsModel,
+    sttModel,
+    ttsModel,
     ttsVoice:
       typeof sanitized.ttsVoice === "string" && sanitized.ttsVoice.trim()
         ? sanitized.ttsVoice.trim()
@@ -294,6 +345,25 @@ function normalizeSpeechSettings(input?: Partial<SpeechSettings> | null): Speech
       sanitized.ttsFormat === "wav" || sanitized.ttsFormat === "opus" || sanitized.ttsFormat === "aac" || sanitized.ttsFormat === "mp3"
         ? sanitized.ttsFormat
         : defaultSpeechSettings.ttsFormat,
+    separateProviders: sanitized.separateProviders === true,
+    stt: {
+      apiKey: typeof sanitized.stt?.apiKey === "string" && sanitized.stt.apiKey.trim() ? sanitized.stt.apiKey.trim() : undefined,
+      hasApiKey: sanitized.stt?.hasApiKey === true || (typeof sanitized.stt?.apiKey === "string" && sanitized.stt.apiKey.trim().length > 0),
+      baseUrl: typeof sanitized.stt?.baseUrl === "string" && sanitized.stt.baseUrl.trim() ? sanitized.stt.baseUrl.trim() : undefined,
+      model:
+        typeof sanitized.stt?.model === "string" && sanitized.stt.model.trim()
+          ? sanitized.stt.model.trim()
+          : sttModel,
+    },
+    tts: {
+      apiKey: typeof sanitized.tts?.apiKey === "string" && sanitized.tts.apiKey.trim() ? sanitized.tts.apiKey.trim() : undefined,
+      hasApiKey: sanitized.tts?.hasApiKey === true || (typeof sanitized.tts?.apiKey === "string" && sanitized.tts.apiKey.trim().length > 0),
+      baseUrl: typeof sanitized.tts?.baseUrl === "string" && sanitized.tts.baseUrl.trim() ? sanitized.tts.baseUrl.trim() : undefined,
+      model:
+        typeof sanitized.tts?.model === "string" && sanitized.tts.model.trim()
+          ? sanitized.tts.model.trim()
+          : ttsModel,
+    },
   }
 }
 
@@ -400,13 +470,16 @@ function getModelKey(model: { providerId: string; modelId: string }): string {
   return `${model.providerId}/${model.modelId}`
 }
 
-function buildRecentFolderList(folderPath: string, source: RecentFolder[]): RecentFolder[] {
-  const existing = source.find((f) => f.path === folderPath)
-  const folders = source.filter((f) => f.path !== folderPath)
+function buildRecentFolderList(folderPath: string, source: RecentFolder[], aliasPath?: string): RecentFolder[] {
+  const matchingPaths = new Set([folderPath, aliasPath].filter((value): value is string => Boolean(value)))
+  const aliasEntry = aliasPath ? source.find((folder) => folder.path === aliasPath) : undefined
+  const canonicalEntry = source.find((folder) => folder.path === folderPath)
+  const projectName = aliasEntry?.projectName ?? canonicalEntry?.projectName
+  const folders = source.filter((folder) => !matchingPaths.has(folder.path))
   folders.unshift({
     path: folderPath,
     lastAccessed: Date.now(),
-    ...(existing?.projectName ? { projectName: existing.projectName } : {}),
+    ...(projectName ? { projectName } : {}),
   })
   return folders.slice(0, MAX_RECENT_FOLDERS)
 }
@@ -593,9 +666,9 @@ function addEnvironmentVariable(key: string, value: string, secure: boolean = tr
 }
 
 function removeEnvironmentVariable(key: string): void {
-  const current = serverSettings().environmentVariables
-  const { [key]: removed, ...rest } = current
-  updateEnvironmentVariables(rest)
+  void patchConfigOwner("server", { environmentVariables: { [key]: null } }).catch((error) =>
+    log.error("Failed to remove environment variable", error),
+  )
 }
 
 function isSecureEnvVar(key: string): boolean {
@@ -630,18 +703,7 @@ function updateLogLevel(level: ServerLogLevel): void {
 }
 
 async function updateSpeechSettings(updates: SpeechSettingsUpdate): Promise<void> {
-  const apiKeyPatch = updates.apiKey
-  const { apiKey: _apiKey, ...restUpdates } = updates
-  const next = normalizeSpeechSettings({
-    ...serverSettings().speech,
-    ...restUpdates,
-    ...(apiKeyPatch === null ? {} : { apiKey: apiKeyPatch }),
-  })
-  const { hasApiKey: _hasApiKey, ...persistedSpeech } = next
-  const patch = {
-    ...persistedSpeech,
-    ...(apiKeyPatch === null ? { apiKey: null } : {}),
-  }
+  const patch = buildSpeechPatch(updates)
   try {
     await patchConfigOwner("server", { speech: patch })
   } catch (error) {
@@ -711,9 +773,9 @@ function removeRemoteServerProfile(id: string): void {
   void patchStateOwner("ui", { remoteServers: next }).catch((error) => log.error("Failed to remove remote server", error))
 }
 
-function recordWorkspaceLaunch(folderPath: string, binaryPath?: string): void {
+function recordWorkspaceLaunch(folderPath: string, binaryPath?: string, aliasPath?: string): void {
   const targetBinary = binaryPath && binaryPath.trim().length > 0 ? binaryPath : serverSettings().opencodeBinary
-  const nextFolders = buildRecentFolderList(folderPath, recentFolders())
+  const nextFolders = buildRecentFolderList(folderPath, recentFolders(), aliasPath)
   const nextBinaries = buildBinaryList(targetBinary, undefined, opencodeBinaries())
 
   void patchStateOwner("ui", { recentFolders: nextFolders, opencodeBinaries: nextBinaries }).catch((error) =>
@@ -779,11 +841,11 @@ function setDiffViewMode(mode: DiffViewMode): void {
   updateUiSettings({ diffViewMode: mode })
 }
 
-function setToolOutputExpansion(mode: ExpansionPreference): void {
+function setToolOutputExpansion(mode: VisibilityPreference): void {
   const current = preferences()
-  if (current.toolOutputExpansion === mode && current.toolCallExpansionDefaults.tools.other === mode) return
+  if (current.toolCallExpansionDefaults.tools.other === mode) return
   updateUiSettings({
-    toolOutputExpansion: mode,
+    toolOutputExpansion: mode === "hidden" ? current.toolOutputExpansion : mode,
     toolCallExpansionDefaults: {
       ...current.toolCallExpansionDefaults,
       preset: "custom",
@@ -795,7 +857,7 @@ function setToolOutputExpansion(mode: ExpansionPreference): void {
   })
 }
 
-function setDiagnosticsExpansion(mode: ExpansionPreference): void {
+function setDiagnosticsExpansion(mode: VisibilityPreference): void {
   if (preferences().diagnosticsExpansion === mode) return
   updateUiSettings({ diagnosticsExpansion: mode })
 }
diff --git a/packages/ui/src/stores/releases.ts b/packages/ui/src/stores/releases.ts
index f1f6c4e7..38dcd94b 100644
--- a/packages/ui/src/stores/releases.ts
+++ b/packages/ui/src/stores/releases.ts
@@ -1,9 +1,11 @@
 import { createEffect, createSignal } from "solid-js"
+import { invoke } from "@tauri-apps/api/core"
 import type { ServerMeta, SupportMeta } from "../../../server/src/api-types"
 import { getServerMeta } from "../lib/server-meta"
 import { showToastNotification, ToastHandle } from "../lib/notifications"
 import { getLogger } from "../lib/logger"
 import { tGlobal } from "../lib/i18n"
+import { isLocalWindow, isTauriHost } from "../lib/runtime-env"
 import { hasInstances, showFolderSelection } from "./ui"
 
 const log = getLogger("actions")
@@ -61,6 +63,7 @@ function ensureVisibilityEffect() {
           ? {
               label: tGlobal("releases.upgradeRequired.action.getUpdate"),
               href: support.latestServerUrl,
+              onClick: isTauriHost() && isLocalWindow() && navigator.userAgent.includes("Windows") ? () => invoke("install_stable_update") : undefined,
             }
           : undefined,
       })
diff --git a/packages/ui/src/stores/restore-creation-cancellation.ts b/packages/ui/src/stores/restore-creation-cancellation.ts
new file mode 100644
index 00000000..dccf8ca4
--- /dev/null
+++ b/packages/ui/src/stores/restore-creation-cancellation.ts
@@ -0,0 +1,11 @@
+import { serverApi } from "../lib/api-client"
+import { retryWithBackoff } from "../lib/retry-utils"
+
+export function cancelRestoreCreation(requestId: string): Promise<void> {
+  return retryWithBackoff(() => serverApi.cancelWorkspaceCreation(requestId), {
+    maxAttempts: 4,
+    initialDelayMs: 250,
+    maxDelayMs: 2_000,
+    backoffMultiplier: 4,
+  })
+}
diff --git a/packages/ui/src/stores/restore-workspace-commit-gates.test.ts b/packages/ui/src/stores/restore-workspace-commit-gates.test.ts
new file mode 100644
index 00000000..0ee5b872
--- /dev/null
+++ b/packages/ui/src/stores/restore-workspace-commit-gates.test.ts
@@ -0,0 +1,81 @@
+import assert from "node:assert/strict"
+import { readFileSync } from "node:fs"
+import { describe, it } from "node:test"
+import type { WorkspaceDescriptor } from "../../../server/src/api-types.ts"
+import { RestoreWorkspaceCommitGates } from "./restore-workspace-commit-gates.ts"
+
+const workspace = (
+  status: WorkspaceDescriptor["status"],
+  updatedAt: string,
+  values: Partial<WorkspaceDescriptor> = {},
+): WorkspaceDescriptor => ({
+  id: "workspace-1", requestId: "request-1", path: "/work", name: "work", status,
+  proxyPath: "", binaryId: "opencode", binaryLabel: "OpenCode", createdAt: "2026-01-01T00:00:00Z",
+  updatedAt, ...values,
+})
+
+describe("restore workspace commit gates", () => {
+  it("integrates refresh and terminal events without bypassing the gate", () => {
+    const source = readFileSync(new URL("./instances.ts", import.meta.url), "utf8")
+    const refresh = source.slice(source.indexOf("async function refreshWorkspaceList"), source.indexOf("const initialWorkspaceLoad"))
+    assert.ok(refresh.indexOf("restoreCreationCommitGates.deferRefreshWorkspace(workspace)") < refresh.indexOf("upsertWorkspace(workspace)"))
+    assert.match(source, /restoreCreationCommitGates\.deferStopped\(event\.workspaceId, event\.reason\)/)
+    assert.match(source, /settleRestoreWorkspaceTerminal\(committedWorkspace, terminal\)/)
+  })
+
+  it("defers refresh/SSE descriptors and prefers a ready HTTP response over stale created state", () => {
+    const gates = new RestoreWorkspaceCommitGates<WorkspaceDescriptor>()
+    gates.begin("request-1", Promise.resolve())
+    assert.equal(gates.deferWorkspace(workspace("starting", "2026-01-01T00:00:01Z")), true)
+    const response = workspace("ready", "2026-01-01T00:00:02Z", { port: 3000 })
+    assert.equal(gates.resolve("request-1", response).workspace, response)
+  })
+
+  it("defers a refresh descriptor without request correlation when its path is gated", () => {
+    const gates = new RestoreWorkspaceCommitGates<WorkspaceDescriptor>()
+    gates.begin("request-1", Promise.resolve(), String.raw`C:\Work`)
+    const refresh = workspace("starting", "2026-01-01T00:00:01Z", {
+      requestId: undefined, path: "c:/work/",
+    })
+    assert.equal(gates.deferRefreshWorkspace(refresh), true)
+    assert.equal(gates.resolve("request-1", workspace("ready", "2026-01-01T00:00:02Z")).workspace.status, "ready")
+  })
+
+  it("uses a newer equally-advanced SSE descriptor", () => {
+    const gates = new RestoreWorkspaceCommitGates<WorkspaceDescriptor>()
+    gates.begin("request-1", Promise.resolve())
+    const response = workspace("ready", "2026-01-01T00:00:02Z", { port: 3000 })
+    const event = workspace("ready", "2026-01-01T00:00:03Z", { port: 4000 })
+    gates.deferWorkspace(event)
+    assert.equal(gates.resolve("request-1", response).workspace, event)
+  })
+
+  it("retains error and stopped terminals until create handling resolves them", () => {
+    const gates = new RestoreWorkspaceCommitGates<WorkspaceDescriptor>()
+    gates.begin("request-1", Promise.resolve())
+    gates.deferWorkspace(workspace("starting", "2026-01-01T00:00:01Z"))
+    assert.equal(gates.deferStopped("workspace-1", "server stopped"), true)
+    assert.deepEqual(gates.resolve("request-1", workspace("ready", "2026-01-01T00:00:02Z")).terminal,
+      { status: "stopped", message: "server stopped" })
+    gates.end("request-1")
+    assert.equal(gates.deferStopped("workspace-1"), false, "terminal events are handled normally after commit")
+  })
+
+  it("correlates a stopped event that arrives before the HTTP response binds its workspace ID", () => {
+    const gates = new RestoreWorkspaceCommitGates<WorkspaceDescriptor>()
+    gates.begin("request-1", Promise.resolve())
+    assert.equal(gates.deferStopped("workspace-1", "stopped before response"), false)
+    gates.bindResponse("request-1", "workspace-1")
+    assert.deepEqual(gates.resolve("request-1", workspace("ready", "2026-01-01T00:00:02Z")).terminal,
+      { status: "stopped", message: "stopped before response" })
+  })
+
+  it("retains a correlated workspace error over a ready response", () => {
+    const gates = new RestoreWorkspaceCommitGates<WorkspaceDescriptor>()
+    gates.begin("request-1", Promise.resolve())
+    gates.deferWorkspace(workspace("error", "2026-01-01T00:00:03Z", { error: "launch failed" }))
+    const resolved = gates.resolve("request-1", workspace("ready", "2026-01-01T00:00:02Z"))
+    assert.equal(resolved.workspace.status, "error")
+    assert.deepEqual(resolved.terminal, { status: "error", message: "launch failed" })
+  })
+})
diff --git a/packages/ui/src/stores/restore-workspace-commit-gates.ts b/packages/ui/src/stores/restore-workspace-commit-gates.ts
new file mode 100644
index 00000000..245e1f09
--- /dev/null
+++ b/packages/ui/src/stores/restore-workspace-commit-gates.ts
@@ -0,0 +1,111 @@
+import type { WorkspaceDescriptor } from "../../../server/src/api-types"
+import { normalizeWorkspacePath } from "./app-session-reconciliation"
+
+export interface RestoreWorkspaceTerminal {
+  status: "error" | "stopped"
+  message?: string
+}
+
+export interface RestoreWorkspaceCommitGate<T extends WorkspaceDescriptor> {
+  requestId: string
+  wait: Promise<void>
+  workspace?: T
+  terminal?: RestoreWorkspaceTerminal
+  workspaceIds: Set<string>
+  expectedPath?: string
+}
+
+const statusRank = (status: WorkspaceDescriptor["status"]) =>
+  status === "error" || status === "stopped" ? 3 : status === "ready" ? 2 : 1
+
+export function preferAdvancedWorkspaceDescriptor<T extends WorkspaceDescriptor>(current: T, candidate: T): T {
+  const rankDifference = statusRank(candidate.status) - statusRank(current.status)
+  if (rankDifference !== 0) return rankDifference > 0 ? candidate : current
+  const currentUpdatedAt = Date.parse(current.updatedAt)
+  const candidateUpdatedAt = Date.parse(candidate.updatedAt)
+  if (Number.isFinite(currentUpdatedAt) && Number.isFinite(candidateUpdatedAt) && currentUpdatedAt !== candidateUpdatedAt) {
+    return candidateUpdatedAt > currentUpdatedAt ? candidate : current
+  }
+  return candidate
+}
+
+export class RestoreWorkspaceCommitGates<T extends WorkspaceDescriptor> {
+  private readonly byRequestId = new Map<string, RestoreWorkspaceCommitGate<T>>()
+  private readonly byWorkspaceId = new Map<string, RestoreWorkspaceCommitGate<T>>()
+  private readonly stoppedByWorkspaceId = new Map<string, RestoreWorkspaceTerminal>()
+
+  begin(requestId: string, wait: Promise<void>, expectedPath?: string): RestoreWorkspaceCommitGate<T> {
+    const gate = {
+      requestId, wait, workspaceIds: new Set<string>(),
+      ...(expectedPath ? { expectedPath: normalizeWorkspacePath(expectedPath) } : {}),
+    }
+    this.byRequestId.set(requestId, gate)
+    return gate
+  }
+
+  bindResponse(requestId: string, workspaceId: string): void {
+    const gate = this.byRequestId.get(requestId)
+    if (!gate) return
+    gate.workspaceIds.add(workspaceId)
+    this.byWorkspaceId.set(workspaceId, gate)
+    const stopped = this.stoppedByWorkspaceId.get(workspaceId)
+    if (stopped) {
+      gate.terminal = stopped
+      this.stoppedByWorkspaceId.delete(workspaceId)
+    }
+  }
+
+  deferWorkspace(workspace: T): boolean {
+    const gate = workspace.requestId
+      ? this.byRequestId.get(workspace.requestId) ?? this.byWorkspaceId.get(workspace.id)
+      : this.byWorkspaceId.get(workspace.id)
+    if (!gate) return false
+    gate.workspace = gate.workspace
+      ? preferAdvancedWorkspaceDescriptor(gate.workspace, workspace)
+      : workspace
+    gate.workspaceIds.add(workspace.id)
+    this.byWorkspaceId.set(workspace.id, gate)
+    if (workspace.status === "error" || workspace.status === "stopped") {
+      gate.terminal = { status: workspace.status, message: workspace.error }
+    }
+    return true
+  }
+
+  deferRefreshWorkspace(workspace: T): boolean {
+    if (this.deferWorkspace(workspace)) return true
+    const path = normalizeWorkspacePath(workspace.path)
+    return [...this.byRequestId.values()].some((gate) => gate.expectedPath === path)
+  }
+
+  deferStopped(workspaceId: string, message?: string): boolean {
+    const gate = this.byWorkspaceId.get(workspaceId)
+    const terminal = { status: "stopped" as const, message }
+    if (!gate) {
+      if (this.byRequestId.size > 0) this.stoppedByWorkspaceId.set(workspaceId, terminal)
+      return false
+    }
+    gate.terminal = terminal
+    return true
+  }
+
+  resolve(requestId: string, response: T): { workspace: T; terminal?: RestoreWorkspaceTerminal } {
+    const gate = this.byRequestId.get(requestId)
+    return {
+      workspace: gate?.workspace
+        ? preferAdvancedWorkspaceDescriptor(response, gate.workspace)
+        : response,
+      ...(gate?.terminal ? { terminal: gate.terminal } : {}),
+    }
+  }
+
+  end(requestId: string): void {
+    const gate = this.byRequestId.get(requestId)
+    if (!gate) return
+    this.byRequestId.delete(requestId)
+    for (const workspaceId of gate.workspaceIds) {
+      if (this.byWorkspaceId.get(workspaceId) === gate) this.byWorkspaceId.delete(workspaceId)
+      this.stoppedByWorkspaceId.delete(workspaceId)
+    }
+    if (this.byRequestId.size === 0) this.stoppedByWorkspaceId.clear()
+  }
+}
diff --git a/packages/ui/src/stores/session-actions.ts b/packages/ui/src/stores/session-actions.ts
index aa54c144..6c0db47c 100644
--- a/packages/ui/src/stores/session-actions.ts
+++ b/packages/ui/src/stores/session-actions.ts
@@ -4,7 +4,7 @@ import { getRootClient } from "./opencode-client"
 import { getOpenCodeWorkspaceIdForSession } from "./opencode-workspaces"
 
 import { addRecentModelPreference, getModelThinkingSelection, setAgentModelPreference } from "./preferences"
-import { providers, sessions, withSession } from "./session-state"
+import { beginSessionGenerationAdmission, providers, sessions, withSession } from "./session-state"
 import { getDefaultModel, isModelValid } from "./session-models"
 import { updateSessionInfo } from "./message-v2/session-info"
 import { messageStoreBus } from "./message-v2/bus"
@@ -216,14 +216,21 @@ async function sendMessage(
   try {
     log.info("session.promptAsync", { instanceId, sessionId, requestBody })
     const workspacePayload = await getSessionWorkspacePayload(instanceId, sessionId)
-    await requestData(
-      client.session.promptAsync({
-        sessionID: sessionId,
-        ...workspacePayload,
-        ...(requestBody as any),
-      }),
-      "session.promptAsync",
-    )
+    const admission = beginSessionGenerationAdmission(instanceId, sessionId)
+    try {
+      await requestData(
+        client.session.promptAsync({
+          sessionID: sessionId,
+          ...workspacePayload,
+          ...(requestBody as any),
+        }),
+        "session.promptAsync",
+      )
+      admission.complete()
+    } catch (error) {
+      admission.rollback()
+      throw error
+    }
   } catch (error) {
     log.error("Failed to send prompt", error)
     throw error
@@ -271,14 +278,22 @@ async function executeCustomCommand(
     if (variant) body.variant = variant
   }
 
-  await requestData(
-    client.session.command({
-      sessionID: sessionId,
-      ...(await getSessionWorkspacePayload(instanceId, sessionId)),
-      ...(body as any),
-    }),
-    "session.command",
-  )
+  const workspacePayload = await getSessionWorkspacePayload(instanceId, sessionId)
+  const admission = beginSessionGenerationAdmission(instanceId, sessionId)
+  try {
+    await requestData(
+      client.session.command({
+        sessionID: sessionId,
+        ...workspacePayload,
+        ...(body as any),
+      }),
+      "session.command",
+    )
+    admission.complete()
+  } catch (error) {
+    admission.rollback()
+    throw error
+  }
 }
 
 async function runShellCommand(instanceId: string, sessionId: string, command: string): Promise<void> {
@@ -296,15 +311,23 @@ async function runShellCommand(instanceId: string, sessionId: string, command: s
 
   const agent = session.agent || "build"
 
-  await requestData(
-    client.session.shell({
-      sessionID: sessionId,
-      ...(await getSessionWorkspacePayload(instanceId, sessionId)),
-      agent,
-      command,
-    }),
-    "session.shell",
-  )
+  const workspacePayload = await getSessionWorkspacePayload(instanceId, sessionId)
+  const admission = beginSessionGenerationAdmission(instanceId, sessionId)
+  try {
+    await requestData(
+      client.session.shell({
+        sessionID: sessionId,
+        ...workspacePayload,
+        agent,
+        command,
+      }),
+      "session.shell",
+    )
+    admission.complete()
+  } catch (error) {
+    admission.rollback()
+    throw error
+  }
 }
 
 async function abortSession(instanceId: string, sessionId: string): Promise<void> {
diff --git a/packages/ui/src/stores/session-api.ts b/packages/ui/src/stores/session-api.ts
index 98ea2065..28b84ce6 100644
--- a/packages/ui/src/stores/session-api.ts
+++ b/packages/ui/src/stores/session-api.ts
@@ -9,21 +9,28 @@ import {
 import type { Message } from "../types/message"
 import type { Session as SDKSession, SessionListResponse } from "@opencode-ai/sdk/v2/client"
 
-import { instances } from "./instances"
+import { instances, reconcilePendingSessionIndicators } from "./instances"
 import { preferences, setAgentModelPreference } from "./preferences"
 import {
   activeSessionId,
+  activeParentSessionId,
   agents,
+  clearActiveSession,
+  clearActiveParentSession,
+  setActiveSession,
   clearSessionDraftPrompt,
+  cancelSessionGenerationAdmissions,
+  markSessionDeletedAuthoritative,
+  getAuthoritativelyDeletedSessionIdsForInstance,
   getDescendantSessions,
   isBlankSession,
   messagesLoaded,
   getSessionMessagesLoadError,
-  pruneDraftPrompts,
   providers,
-  setActiveSessionId,
   setAgents,
   setMessagesLoaded,
+  advanceMessageLoadEpoch,
+  isCurrentMessageLoad,
   setSessionMessagesLoadError,
   setProviders,
   setSessionInfoByInstance,
@@ -43,7 +50,10 @@ import {
   clearSessionSearch,
   isLatestSessionSearch,
   setSessionSearchResults,
+  setSessionListError,
+  setSessionExpanded,
 } from "./session-state"
+import { deleteSessionAttachments } from "./attachments"
 import { DEFAULT_MODEL_OUTPUT_LIMIT, getDefaultModel, isModelValid } from "./session-models"
 import { normalizeMessagePart } from "./message-v2/normalizers"
 import { updateSessionInfo } from "./message-v2/session-info"
@@ -51,41 +61,114 @@ import { seedSessionMessagesV2, reconcilePendingPermissionsV2, reconcilePendingQ
 import { messageStoreBus } from "./message-v2/bus"
 import { clearCacheForSession } from "../lib/global-cache"
 import { getLogger } from "../lib/logger"
-import { requestData } from "../lib/opencode-api"
+import { getOpencodeErrorMessage, requestData } from "../lib/opencode-api"
 import { getRootClient } from "./opencode-client"
-import { getWorktreeSlugForSession, migrateLegacyWorktreeMapToSessionMetadata, pruneStaleLegacyWorktreeMapEntries, removeLegacyParentSessionMapping, setWorktreeSlugForParentSession } from "./worktrees"
-import { getOpenCodeWorkspaceIdForSession } from "./opencode-workspaces"
+import { tGlobal } from "../lib/i18n"
+import {
+  getWorktreeSlugForSession,
+  getWorktreeSlugForDirectory,
+  getWorktrees,
+  migrateLegacyWorktreeMapToSessionMetadata,
+  pruneStaleLegacyWorktreeMapEntries,
+  removeLegacyParentSessionMapping,
+  setWorktreeSlugForParentSession,
+} from "./worktrees"
+import { getOpenCodeWorkspaceIdForSession, getOpenCodeWorkspaceIdForWorktree } from "./opencode-workspaces"
 import { hydrateSessionMetadataWithClient } from "./session-metadata"
-import { PROJECT_SESSION_LIST_LIMIT, buildProjectSessionListOptions } from "./session-list-options"
+import { preferSessionMetadata, shouldReplaceSessionMetadata } from "./session-metadata-completeness"
+import {
+  PROJECT_SESSION_LIST_LIMIT,
+  buildProjectSessionListOptions,
+  filterProjectScopedSessions,
+  getAuthoritativelyMissingSessionIds,
+  isProjectSessionListComplete,
+} from "./session-list-options"
+import { mergeFetchedSessionRuntimeState, resolveAuthoritativeGenerationRecovery } from "./session-generation-recovery"
 
 const log = getLogger("api")
+const sessionListRequestIds = new Map<string, number>()
+let nextSessionListRequestId = 0
+const pendingMetadataHydrations = new Map<string, Promise<void>>()
+const sessionWorkspaceHints = new Map<string, Map<string, string>>()
+messageStoreBus.onInstanceDestroyed((instanceId) => sessionWorkspaceHints.delete(instanceId))
 
-function getErrorMessage(error: unknown): string {
-  if (!error) return "Failed to load messages"
+function beginSessionListRequest(instanceId: string): number {
+  const requestId = ++nextSessionListRequestId
+  sessionListRequestIds.set(instanceId, requestId)
+  return requestId
+}
 
-  const cause = (error as any)?.cause
-  if (cause && cause !== error) {
-    const causeMessage = getErrorMessage(cause)
-    if (causeMessage) return causeMessage
-  }
+function isLatestSessionListRequest(instanceId: string, requestId: number): boolean {
+  return sessionListRequestIds.get(instanceId) === requestId
+}
 
-  const dataMessage = (error as any)?.data?.message
-  if (typeof dataMessage === "string" && dataMessage.trim()) return dataMessage
-
-  const errorMessage = (error as any)?.message
-  if (typeof errorMessage === "string" && errorMessage.trim()) return errorMessage
-
-  const errorText = (error as any)?.error
-  if (typeof errorText === "string" && errorText.trim()) return errorText
-
-  return "Failed to load messages"
+function clearSessionListRequestState(instanceId: string): void {
+  sessionListRequestIds.delete(instanceId)
+  setSessionListError(instanceId, null)
+  setLoading((prev) => {
+    if (!prev.fetchingSessions.has(instanceId)) return prev
+    const fetchingSessions = new Map(prev.fetchingSessions)
+    fetchingSessions.delete(instanceId)
+    return { ...prev, fetchingSessions }
+  })
 }
 
 async function getSessionWorkspacePayload(instanceId: string, sessionId: string): Promise<{ workspace?: string }> {
+  const hinted = sessionWorkspaceHints.get(instanceId)?.get(sessionId)
+  if (hinted) return { workspace: hinted }
   const workspace = await getOpenCodeWorkspaceIdForSession(instanceId, sessionId)
   return workspace ? { workspace } : {}
 }
 
+async function getSessionWorkspaceCandidates(
+  instanceId: string,
+  sessionId: string,
+  fallback: { workspace?: string } = {},
+): Promise<Array<{ workspace?: string }>> {
+  const candidates: Array<{ workspace?: string }> = []
+  const seen = new Set<string>()
+  const add = (candidate: { workspace?: string }) => {
+    const key = candidate.workspace ?? "root"
+    if (seen.has(key)) return
+    seen.add(key)
+    candidates.push(candidate)
+  }
+  add(await getSessionWorkspacePayload(instanceId, sessionId))
+  add(fallback)
+  add({})
+  for (const worktree of getWorktrees(instanceId)) {
+    if (!worktree.slug || worktree.slug === "root") continue
+    const workspace = await getOpenCodeWorkspaceIdForWorktree(instanceId, worktree.slug)
+    if (workspace) add({ workspace })
+  }
+  return candidates
+}
+
+function rememberSessionWorkspace(instanceId: string, sessionId: string, workspace: string | undefined): void {
+  if (!workspace) return
+  const hints = new Map(sessionWorkspaceHints.get(instanceId) ?? new Map())
+  hints.set(sessionId, workspace)
+  sessionWorkspaceHints.set(instanceId, hints)
+}
+
+async function recordSessionWorkspaceHints(instanceId: string, apiSessions: SDKSession[]): Promise<void> {
+  const hints = new Map(sessionWorkspaceHints.get(instanceId) ?? new Map<string, string>())
+  const workspaceBySlug = new Map<string, Promise<string | null>>()
+  await Promise.all(apiSessions.map(async (session) => {
+    const directory = (session as SDKSession & { directory?: string }).directory
+    const slug = getWorktreeSlugForDirectory(instanceId, directory)
+    if (!slug || slug === "root") return
+    let workspace = workspaceBySlug.get(slug)
+    if (!workspace) {
+      workspace = getOpenCodeWorkspaceIdForWorktree(instanceId, slug)
+      workspaceBySlug.set(slug, workspace)
+    }
+    const workspaceId = await workspace
+    if (workspaceId) hints.set(session.id, workspaceId)
+  }))
+  sessionWorkspaceHints.set(instanceId, hints)
+}
+
 interface SessionForkResponse {
   id: string
   title?: string
@@ -115,6 +198,8 @@ type V2SessionListOptions = {
 
 type ProjectSessionListResponse = {
   data: SDKSession[]
+  listedIds: Set<string>
+  complete: boolean
 }
 
 function getKnownParentId(session: SDKSession | Session): string | null | undefined {
@@ -142,7 +227,13 @@ async function fetchV2Sessions(instanceId: string, options: V2SessionListOptions
   const client = getRootClient(instanceId)
   const listOptions = buildProjectSessionListOptions(options)
   const data = await requestData<SessionListResponse>(client.session.list(listOptions), "session.list")
-  return { data }
+  const allowedDirectories = [options.directory, ...getWorktrees(instanceId).map((worktree) => worktree.directory)]
+
+  return {
+    data: filterProjectScopedSessions(data, allowedDirectories),
+    listedIds: new Set(data.map((session) => session.id)),
+    complete: isProjectSessionListComplete(data.length),
+  }
 }
 
 function getV2SessionItems(response: ProjectSessionListResponse): SDKSession[] {
@@ -154,15 +245,115 @@ async function hydrateMissingSessionMetadata(instanceId: string, sessionIds: str
   if (uniqueIds.length === 0) return
 
   const client = getRootClient(instanceId)
-  for (const sessionId of uniqueIds) {
-    const session = sessions().get(instanceId)?.get(sessionId)
-    if (!session || session.metadata !== undefined) continue
-    try {
-      await hydrateSessionMetadataWithClient(client, instanceId, sessionId)
-    } catch (error) {
-      log.warn("Failed to hydrate session metadata", { instanceId, sessionId, error })
+  let nextIndex = 0
+  const worker = async () => {
+    while (nextIndex < uniqueIds.length) {
+      const sessionId = uniqueIds[nextIndex++]!
+      const session = sessions().get(instanceId)?.get(sessionId)
+      if (!session || !shouldReplaceSessionMetadata(session.metadata)) continue
+      try {
+        await hydrateSessionMetadata(instanceId, sessionId, client)
+      } catch (error) {
+        log.warn("Failed to hydrate session metadata", { instanceId, sessionId, error })
+      }
     }
   }
+  await Promise.all(Array.from({ length: Math.min(8, uniqueIds.length) }, worker))
+}
+
+function hydrateSessionMetadata(instanceId: string, sessionId: string, client = getRootClient(instanceId)): Promise<void> {
+  const key = `${instanceId}:${sessionId}`
+  const current = pendingMetadataHydrations.get(key)
+  if (current) return current
+  const hydration = (async () => {
+    const candidates = await getSessionWorkspaceCandidates(instanceId, sessionId)
+    let lastError: unknown
+    for (const delayMs of [0, 100, 400]) {
+      if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs))
+      for (const candidate of candidates) {
+        try {
+          await hydrateSessionMetadataWithClient(client, instanceId, sessionId, candidate)
+          rememberSessionWorkspace(instanceId, sessionId, candidate.workspace)
+          return
+        } catch (error) {
+          lastError = error
+        }
+      }
+    }
+    throw lastError
+  })().finally(() => pendingMetadataHydrations.delete(key))
+  pendingMetadataHydrations.set(key, hydration)
+  return hydration
+}
+
+async function hydrateRestoredSessionChain(
+  instanceId: string,
+  requestedIds: Array<string | null | undefined>,
+  signal?: AbortSignal,
+): Promise<void> {
+  const client = getRootClient(instanceId)
+  const pending = requestedIds.filter((id): id is string => Boolean(id) && id !== "info")
+  const visited = new Set<string>()
+  let chainWorkspacePayload: { workspace?: string } = {}
+  while (pending.length > 0) {
+    signal?.throwIfAborted()
+    const sessionId = pending.shift()!
+    if (visited.has(sessionId)) continue
+    visited.add(sessionId)
+    if (getAuthoritativelyDeletedSessionIdsForInstance(instanceId).has(sessionId)) continue
+
+    let session = sessions().get(instanceId)?.get(sessionId)
+    if (!session) {
+      try {
+        const workspaceCandidates = await getSessionWorkspaceCandidates(instanceId, sessionId, chainWorkspacePayload)
+        signal?.throwIfAborted()
+        let apiSession: SDKSession | undefined
+        let hydratedWorkspace: string | undefined
+        let lastError: unknown
+        for (const workspacePayload of workspaceCandidates) {
+          try {
+            apiSession = await requestData<SDKSession>(
+              client.session.get({ sessionID: sessionId, ...workspacePayload }),
+              "session.get",
+            )
+            hydratedWorkspace = workspacePayload.workspace
+            break
+          } catch (error) {
+            lastError = error
+          }
+        }
+        if (!apiSession) throw lastError
+        signal?.throwIfAborted()
+        rememberSessionWorkspace(instanceId, sessionId, hydratedWorkspace)
+        setSessions((prev) => {
+          if (getAuthoritativelyDeletedSessionIdsForInstance(instanceId).has(sessionId) || signal?.aborted) return prev
+          const next = new Map(prev)
+          const instanceSessions = new Map(next.get(instanceId) ?? new Map())
+          instanceSessions.set(sessionId, toClientSessionV2(instanceId, apiSession, instanceSessions.get(sessionId)))
+          next.set(instanceId, instanceSessions)
+          return next
+        })
+        session = sessions().get(instanceId)?.get(sessionId)
+        if (session?.parentId === null) prependSessionListId(instanceId, sessionId)
+      } catch (error) {
+        if (signal?.aborted) throw error
+        log.warn("Failed to hydrate restored session", { instanceId, sessionId, error })
+        continue
+      }
+    } else if (shouldReplaceSessionMetadata(session.metadata)) {
+      try {
+        await hydrateSessionMetadata(instanceId, sessionId, client)
+      } catch (error) {
+        if (signal?.aborted) throw error
+        log.warn("Failed to hydrate restored session metadata", { instanceId, sessionId, error })
+      }
+    }
+    if (session?.parentId === null) {
+      const rootWorkspacePayload = await getSessionWorkspacePayload(instanceId, session.id)
+      if (rootWorkspacePayload.workspace) chainWorkspacePayload = rootWorkspacePayload
+    }
+    if (session?.parentId) pending.push(session.parentId)
+  }
 }
 
 async function ensureV2ParentChainsLoaded(instanceId: string, apiSessions: SDKSession[], directory?: string): Promise<void> {
@@ -179,8 +370,10 @@ async function ensureV2ParentChainsLoaded(instanceId: string, apiSessions: SDKSe
   setSessions((prev) => {
     const next = new Map(prev)
     const instanceSessions = new Map(next.get(instanceId) ?? new Map())
+    const deletedSessionIds = getAuthoritativelyDeletedSessionIdsForInstance(instanceId)
 
     for (const apiSession of items) {
+      if (deletedSessionIds.has(apiSession.id)) continue
       const existingSession = instanceSessions.get(apiSession.id)
       instanceSessions.set(apiSession.id, toClientSessionV2(instanceId, apiSession, existingSession))
       loaded.set(apiSession.id, apiSession)
@@ -198,35 +391,45 @@ async function fetchSessions(instanceId: string, options?: { reset?: boolean }):
   }
 
   const rootClient = getRootClient(instanceId)
+  const requestId = beginSessionListRequest(instanceId)
 
   setLoading((prev) => {
     const next = { ...prev }
     next.fetchingSessions.set(instanceId, true)
     return next
   })
+  setSessionListError(instanceId, null)
 
   try {
     const sessionListOptions = instance.folder ? { directory: instance.folder } : {}
+    const existingSessions = new Map(sessions().get(instanceId) ?? new Map<string, Session>())
 
     log.info("session.list", { instanceId, limit: PROJECT_SESSION_LIST_LIMIT, directory: sessionListOptions.directory, scope: "project" })
     const response = await fetchV2Sessions(instanceId, sessionListOptions)
+    if (!isLatestSessionListRequest(instanceId, requestId)) return
+    await recordSessionWorkspaceHints(instanceId, getV2SessionItems(response))
 
     let statusById: Record<string, any> = {}
+    let statusResponseKnown = false
     try {
-        const statusResponse = await rootClient.session.status()
+      const statusResponse = await rootClient.session.status()
       if (statusResponse.data && typeof statusResponse.data === "object") {
+        statusResponseKnown = true
         statusById = statusResponse.data as Record<string, any>
       }
     } catch (error) {
       log.error("Failed to fetch session status:", error)
     }
+    if (!isLatestSessionListRequest(instanceId, requestId)) return
 
-    const existingSessions = sessions().get(instanceId)
     const sessionMap = new Map<string, Session>()
 
     for (const apiSession of getV2SessionItems(response)) {
       const existingSession = existingSessions?.get(apiSession.id)
       const existingStatus = existingSession?.status
+      const rawStatus = (apiSession as any)?.status ?? statusById[apiSession.id]
+      const hasType = rawStatus && typeof rawStatus === "object" && typeof rawStatus.type === "string"
+      const runtimeStatusKnown = Boolean(hasType || statusResponseKnown || existingSession?.runtimeStatusKnown)
 
       let status: SessionStatus
       let retry = existingSession?.retry ?? null
@@ -234,39 +437,57 @@ async function fetchSessions(instanceId: string, options?: { reset?: boolean }):
         status = "compacting"
         retry = null
       } else {
-        const rawStatus = (apiSession as any)?.status ?? statusById[apiSession.id]
-        const hasType = rawStatus && typeof rawStatus === "object" && typeof rawStatus.type === "string"
         status = hasType ? mapSdkSessionStatus(rawStatus) : existingStatus ?? "idle"
         retry = hasType ? mapSdkSessionRetry(rawStatus) : retry
       }
-
-      const session = toClientSessionV2(instanceId, apiSession, existingSession)
       sessionMap.set(apiSession.id, {
-        ...session,
-        agent: session.agent,
-        model: session.model,
+        ...toClientSessionV2(instanceId, apiSession, existingSession),
         status,
         retry,
         idleSince: getIdleSinceForStatusTransition(existingStatus, status, existingSession?.idleSince),
+        runtimeStatusKnown,
+        generationRecovery: runtimeStatusKnown
+          ? resolveAuthoritativeGenerationRecovery(existingSession?.generationRecovery, status)
+          : existingSession?.generationRecovery ?? null,
       })
     }
 
+    const remotelyDeletedSessionIds = getAuthoritativelyMissingSessionIds(
+      existingSessions.keys(),
+      response.listedIds,
+      response.complete,
+    )
+    for (const sessionId of remotelyDeletedSessionIds) removeSessionRuntimeState(instanceId, sessionId)
+
     setSessions((prev) => {
       const next = new Map(prev)
       const instanceSessions = new Map(next.get(instanceId) ?? new Map())
+      const deletedSessionIds = getAuthoritativelyDeletedSessionIdsForInstance(instanceId)
       for (const session of sessionMap.values()) {
-        instanceSessions.set(session.id, session)
+        const capturedSession = existingSessions.get(session.id)
+        const latestSession = instanceSessions.get(session.id)
+        const merged = mergeFetchedSessionRuntimeState(
+          session,
+          capturedSession,
+          latestSession,
+          deletedSessionIds.has(session.id),
+        )
+        if (merged) instanceSessions.set(session.id, merged)
       }
       next.set(instanceId, instanceSessions)
       return next
     })
 
     const rootIds: string[] = []
+    const seenRootIds = new Set<string>()
     const missingRootSessionIds: string[] = []
     for (const apiSession of getV2SessionItems(response)) {
       const root = getSessionRoot(instanceId, apiSession.id)
       if (root) {
-        if (!rootIds.includes(root.id)) rootIds.push(root.id)
+        if (!seenRootIds.has(root.id)) {
+          seenRootIds.add(root.id)
+          rootIds.push(root.id)
+        }
       } else if (apiSession.parentID) {
         missingRootSessionIds.push(apiSession.id)
       }
@@ -281,7 +502,7 @@ async function fetchSessions(instanceId: string, options?: { reset?: boolean }):
 
     setSessionPage(instanceId, rootIds, false, options?.reset ?? true)
 
-    syncInstanceSessionIndicator(instanceId)
+    reconcilePendingSessionIndicators(instanceId)
 
     setMessagesLoaded((prev) => {
       const next = new Map(prev)
@@ -299,7 +520,6 @@ async function fetchSessions(instanceId: string, options?: { reset?: boolean }):
     })
 
 
-    pruneDraftPrompts(instanceId, new Set(sessions().get(instanceId)?.keys() ?? []))
     void (async () => {
       await hydrateMissingSessionMetadata(instanceId, rootIds)
       await migrateLegacyWorktreeMapToSessionMetadata(instanceId)
@@ -309,13 +529,18 @@ async function fetchSessions(instanceId: string, options?: { reset?: boolean }):
     })
   } catch (error) {
     log.error("Failed to fetch sessions:", error)
+    if (isLatestSessionListRequest(instanceId, requestId)) {
+      setSessionListError(instanceId, getOpencodeErrorMessage(error, tGlobal("sessionList.loadError.detail")))
+    }
     throw error
   } finally {
-    setLoading((prev) => {
-      const next = { ...prev }
-      next.fetchingSessions.set(instanceId, false)
-      return next
-    })
+    if (isLatestSessionListRequest(instanceId, requestId)) {
+      setLoading((prev) => {
+        const next = { ...prev }
+        next.fetchingSessions.set(instanceId, false)
+        return next
+      })
+    }
   }
 }
 
@@ -352,8 +577,10 @@ async function searchSessions(instanceId: string, query: string): Promise<void>
     setSessions((prev) => {
       const next = new Map(prev)
       const instanceSessions = new Map(next.get(instanceId) ?? new Map())
+      const deletedSessionIds = getAuthoritativelyDeletedSessionIdsForInstance(instanceId)
 
       for (const apiSession of searchResults) {
+        if (deletedSessionIds.has(apiSession.id)) continue
         const existingSession = instanceSessions.get(apiSession.id)
         instanceSessions.set(apiSession.id, toClientSessionV2(instanceId, apiSession, existingSession))
       }
@@ -361,13 +588,16 @@ async function searchSessions(instanceId: string, query: string): Promise<void>
       next.set(instanceId, instanceSessions)
       return next
     })
+    void hydrateMissingSessionMetadata(instanceId, searchResults.map((session) => session.id))
 
     await ensureV2ParentChainsLoaded(instanceId, searchResults, instance.folder)
 
     if (!isLatestSessionSearch(instanceId, trimmedQuery, requestId)) return
 
     const hydratedSessions = sessions().get(instanceId)
-    const hasUnrenderableChildResult = searchResults.some((session) => {
+    const deletedSessionIds = getAuthoritativelyDeletedSessionIdsForInstance(instanceId)
+    const currentSearchResults = searchResults.filter((session) => !deletedSessionIds.has(session.id))
+    const hasUnrenderableChildResult = currentSearchResults.some((session) => {
       const parentId = session.parentID
       return Boolean(parentId && !hydratedSessions?.has(parentId))
     })
@@ -378,7 +608,7 @@ async function searchSessions(instanceId: string, query: string): Promise<void>
     }
 
     syncInstanceSessionIndicator(instanceId)
-    setSessionSearchResults(instanceId, trimmedQuery, searchResults.map((session) => session.id), requestId)
+    setSessionSearchResults(instanceId, trimmedQuery, currentSearchResults.map((session) => session.id), requestId)
   } catch (error) {
     log.error("Failed to search sessions:", error)
     if (isLatestSessionSearch(instanceId, trimmedQuery, requestId)) {
@@ -389,6 +619,7 @@ async function searchSessions(instanceId: string, query: string): Promise<void>
 }
 
 function toClientSessionV2(instanceId: string, apiSession: SDKSession, existingSession?: Session): Session {
+  const incomingMetadata = (apiSession as SDKSession & { metadata?: Session["metadata"] }).metadata
   return {
     id: apiSession.id,
     instanceId,
@@ -404,11 +635,14 @@ function toClientSessionV2(instanceId: string, apiSession: SDKSession, existingS
     status: existingSession?.status ?? "idle",
     retry: existingSession?.retry ?? null,
     idleSince: existingSession?.idleSince ?? null,
+    generationRecovery: existingSession?.generationRecovery ?? null,
+    runtimeStatusKnown: existingSession?.runtimeStatusKnown ?? false,
+    generationAdmissionToken: existingSession?.generationAdmissionToken,
     version: existingSession?.version || "0",
     time: {
       ...apiSession.time,
     },
-    metadata: existingSession?.metadata,
+    metadata: preferSessionMetadata(incomingMetadata, existingSession?.metadata),
     revert: existingSession?.revert,
     pendingPermission: existingSession?.pendingPermission,
     pendingQuestion: existingSession?.pendingQuestion,
@@ -649,49 +883,7 @@ async function deleteSession(instanceId: string, sessionId: string): Promise<voi
     log.info(`[HTTP] DELETE /session.delete for instance ${instanceId}`, { sessionId })
     await requestData(client.session.delete({ sessionID: sessionId, ...(await getSessionWorkspacePayload(instanceId, sessionId)) }), "session.delete")
 
-    setSessions((prev) => {
-      const next = new Map(prev)
-      const instanceSessions = next.get(instanceId)
-      if (instanceSessions) {
-        instanceSessions.delete(sessionId)
-        if (instanceSessions.size === 0) {
-          next.delete(instanceId)
-        }
-      }
-      return next
-    })
-
-    syncInstanceSessionIndicator(instanceId)
-    removeSessionListId(instanceId, sessionId)
-
-    clearSessionDraftPrompt(instanceId, sessionId)
-
-    // Drop normalized message state and caches for this session
-    messageStoreBus.getOrCreate(instanceId).clearSession(sessionId)
-    clearCacheForSession(instanceId, sessionId)
-
-    setSessionInfoByInstance((prev) => {
-      const next = new Map(prev)
-      const instanceInfo = next.get(instanceId)
-      if (instanceInfo) {
-        const updatedInstanceInfo = new Map(instanceInfo)
-        updatedInstanceInfo.delete(sessionId)
-        if (updatedInstanceInfo.size === 0) {
-          next.delete(instanceId)
-        } else {
-          next.set(instanceId, updatedInstanceInfo)
-        }
-      }
-      return next
-    })
-
-    if (activeSessionId().get(instanceId) === sessionId) {
-      setActiveSessionId((prev) => {
-        const next = new Map(prev)
-        next.delete(instanceId)
-        return next
-      })
-    }
+    removeSessionRuntimeState(instanceId, sessionId)
 
     // Clean up mapping for deleted parent sessions.
     if (deletingSession?.parentId === null) {
@@ -712,6 +904,61 @@ async function deleteSession(instanceId: string, sessionId: string): Promise<voi
   }
 }
 
+function removeSessionRuntimeState(instanceId: string, sessionId: string): void {
+  sessionWorkspaceHints.get(instanceId)?.delete(sessionId)
+  cancelSessionGenerationAdmissions(instanceId, sessionId)
+  markSessionDeletedAuthoritative(instanceId, sessionId)
+  deleteSessionAttachments(instanceId, sessionId)
+  clearSessionDraftPrompt(instanceId, sessionId)
+  setSessionExpanded(instanceId, sessionId, false)
+
+  setSessions((prev) => {
+    const next = new Map(prev)
+    const instanceSessions = next.get(instanceId)
+    if (instanceSessions) {
+      instanceSessions.delete(sessionId)
+      if (instanceSessions.size === 0) {
+        next.delete(instanceId)
+      }
+    }
+    return next
+  })
+
+  syncInstanceSessionIndicator(instanceId)
+  removeSessionListId(instanceId, sessionId)
+
+  // Drop normalized message state and caches for this session.
+  messageStoreBus.getOrCreate(instanceId).clearSession(sessionId)
+  clearCacheForSession(instanceId, sessionId)
+
+  setSessionInfoByInstance((prev) => {
+    const next = new Map(prev)
+    const instanceInfo = next.get(instanceId)
+    if (instanceInfo) {
+      const updatedInstanceInfo = new Map(instanceInfo)
+      updatedInstanceInfo.delete(sessionId)
+      if (updatedInstanceInfo.size === 0) {
+        next.delete(instanceId)
+      } else {
+        next.set(instanceId, updatedInstanceInfo)
+      }
+    }
+    return next
+  })
+
+  const selectedParentId = activeParentSessionId().get(instanceId)
+  const selectedSessionId = activeSessionId().get(instanceId)
+  if (selectedParentId === sessionId) {
+    clearActiveParentSession(instanceId)
+  } else if (selectedSessionId === sessionId) {
+    if (selectedParentId && sessions().get(instanceId)?.has(selectedParentId)) {
+      setActiveSession(instanceId, selectedParentId)
+    } else {
+      clearActiveSession(instanceId)
+    }
+  }
+}
+
 async function fetchAgents(instanceId: string): Promise<void> {
   const instance = instances().get(instanceId)
   if (!instance || !instance.client) {
@@ -813,7 +1060,7 @@ async function loadMessages(
   }
 
   const isLoading = loading().loadingMessages.get(instanceId)?.has(sessionId)
-  if (isLoading) {
+  if (isLoading && !force) {
     return
   }
 
@@ -830,6 +1077,10 @@ async function loadMessages(
     throw new Error("Session not found")
   }
 
+  const loadEpoch = advanceMessageLoadEpoch(instanceId, sessionId)
+  const messageRevision = messageStoreBus.getOrCreate(instanceId).getSessionRevision(sessionId)
+  let retryAfterRevisionConflict = false
+
   setLoading((prev) => {
     const next = { ...prev }
     const loadingSet = next.loadingMessages.get(instanceId) || new Set()
@@ -846,132 +1097,134 @@ async function loadMessages(
       "session.messages",
     )
 
+    if (!isCurrentMessageLoad(instanceId, sessionId, loadEpoch) || !sessions().get(instanceId)?.has(sessionId)) return
+
     if (!Array.isArray(apiMessages)) {
       return
     }
 
     setSessionMessagesLoadError(instanceId, sessionId, null)
 
-    // Treat empty sessions as loaded to avoid re-fetch loops.
-    setMessagesLoaded((prev) => {
-      const next = new Map(prev)
-      const loadedSet = next.get(instanceId) || new Set()
-      loadedSet.add(sessionId)
-      next.set(instanceId, loadedSet)
-      return next
-    })
-
     if (apiMessages.length === 0) {
-      return
-    }
+      if (messageStoreBus.getOrCreate(instanceId).getSessionRevision(sessionId) !== messageRevision) {
+        retryAfterRevisionConflict = true
+      } else {
+        setMessagesLoaded((prev) => {
+          const next = new Map(prev)
+          const loadedSet = next.get(instanceId) || new Set()
+          loadedSet.add(sessionId)
+          next.set(instanceId, loadedSet)
+          return next
+        })
+      }
+    } else {
+      const messagesInfo = new Map<string, any>()
+      const messages: Message[] = apiMessages.map((apiMessage: any) => {
+        const info = apiMessage.info || apiMessage
+        const role = info.role || "assistant"
+        const messageId = info.id || String(Date.now())
 
-    const messagesInfo = new Map<string, any>()
-    const messages: Message[] = apiMessages.map((apiMessage: any) => {
-      const info = apiMessage.info || apiMessage
-      const role = info.role || "assistant"
-      const messageId = info.id || String(Date.now())
+        messagesInfo.set(messageId, info)
 
-      messagesInfo.set(messageId, info)
+        const parts: any[] = (apiMessage.parts || []).map((part: any) => normalizeMessagePart(part))
 
-      const parts: any[] = (apiMessage.parts || []).map((part: any) => normalizeMessagePart(part))
+        const message: Message = {
+          id: messageId,
+          sessionId,
+          type: role === "user" ? "user" : "assistant",
+          parts,
+          timestamp: info.time?.created || Date.now(),
+          status: "complete" as const,
+          version: 0,
+        }
 
-      const message: Message = {
-        id: messageId,
-        sessionId,
-        type: role === "user" ? "user" : "assistant",
-        parts,
-        timestamp: info.time?.created || Date.now(),
-        status: "complete" as const,
-        version: 0,
+        return message
+      })
+
+      let agentName = ""
+      let providerID = ""
+      let modelID = ""
+
+      for (let i = apiMessages.length - 1; i >= 0; i--) {
+        const apiMessage = apiMessages[i]
+        const info = apiMessage.info || apiMessage
+
+        if (info.role === "assistant") {
+          agentName = (info as any).mode || (info as any).agent || ""
+          providerID = (info as any).providerID || ""
+          modelID = (info as any).modelID || ""
+          if (agentName && providerID && modelID) break
+        }
       }
 
-      return message
-    })
-
-    let agentName = ""
-    let providerID = ""
-    let modelID = ""
-
-    for (let i = apiMessages.length - 1; i >= 0; i--) {
-      const apiMessage = apiMessages[i]
-      const info = apiMessage.info || apiMessage
-
-      if (info.role === "assistant") {
-        agentName = (info as any).mode || (info as any).agent || ""
-        providerID = (info as any).providerID || ""
-        modelID = (info as any).modelID || ""
-        if (agentName && providerID && modelID) break
+      if (!agentName && !providerID && !modelID) {
+        const defaultModel = await getDefaultModel(instanceId, session.agent)
+        if (!isCurrentMessageLoad(instanceId, sessionId, loadEpoch) || !sessions().get(instanceId)?.has(sessionId)) return
+        agentName = session.agent
+        providerID = defaultModel.providerId
+        modelID = defaultModel.modelId
       }
-    }
 
-    if (!agentName && !providerID && !modelID) {
-      const defaultModel = await getDefaultModel(instanceId, session.agent)
-      agentName = session.agent
-      providerID = defaultModel.providerId
-      modelID = defaultModel.modelId
-    }
-
-    setSessions((prev) => {
-      const next = new Map(prev)
-      const nextInstanceSessions = next.get(instanceId)
-      if (!nextInstanceSessions) {
+      setSessions((prev) => {
+        if (!isCurrentMessageLoad(instanceId, sessionId, loadEpoch)) return prev
+        const next = new Map(prev)
+        const nextInstanceSessions = next.get(instanceId)
+        if (!nextInstanceSessions) return next
+        const existingSession = nextInstanceSessions.get(sessionId)
+        if (!existingSession) return next
+        nextInstanceSessions.set(sessionId, {
+          ...existingSession,
+          agent: agentName || existingSession.agent,
+          model: providerID && modelID ? { providerId: providerID, modelId: modelID } : existingSession.model,
+        })
+        next.set(instanceId, nextInstanceSessions)
         return next
+      })
+
+      const sessionForV2 = sessions().get(instanceId)?.get(sessionId) ?? {
+        id: sessionId, title: session?.title, parentId: session?.parentId ?? null, revert: session?.revert,
       }
-
-      const existingSession = nextInstanceSessions.get(sessionId)
-      if (!existingSession) {
-        return next
+      if (!isCurrentMessageLoad(instanceId, sessionId, loadEpoch)) return
+      if (!seedSessionMessagesV2(instanceId, sessionForV2, messages, messagesInfo, messageRevision)) {
+        retryAfterRevisionConflict = true
+      } else {
+        setMessagesLoaded((prev) => {
+          const next = new Map(prev)
+          const loadedSet = next.get(instanceId) || new Set()
+          loadedSet.add(sessionId)
+          next.set(instanceId, loadedSet)
+          return next
+        })
+        reconcilePendingPermissionsV2(instanceId, sessionId)
+        reconcilePendingQuestionsV2(instanceId, sessionId)
       }
-
-      const updatedSession = {
-        ...existingSession,
-        agent: agentName || existingSession.agent,
-        model: providerID && modelID ? { providerId: providerID, modelId: modelID } : existingSession.model,
-      }
-
-      nextInstanceSessions.set(sessionId, updatedSession)
-      next.set(instanceId, nextInstanceSessions)
-      return next
-    })
-
-    setMessagesLoaded((prev) => {
-      const next = new Map(prev)
-      const loadedSet = next.get(instanceId) || new Set()
-      loadedSet.add(sessionId)
-      next.set(instanceId, loadedSet)
-      return next
-    })
-
-    const sessionForV2 = sessions().get(instanceId)?.get(sessionId) ?? {
-      id: sessionId,
-      title: session?.title,
-      parentId: session?.parentId ?? null,
-      revert: session?.revert,
     }
-    seedSessionMessagesV2(instanceId, sessionForV2, messages, messagesInfo)
-
-    // Permissions can be hydrated before messages/tool parts exist in the store.
-    // After message hydration, try to attach any pending permissions to tool-call part ids.
-    reconcilePendingPermissionsV2(instanceId, sessionId)
-    reconcilePendingQuestionsV2(instanceId, sessionId)
   
 
 
   } catch (error) {
     log.error("Failed to load messages:", error)
-    setSessionMessagesLoadError(instanceId, sessionId, getErrorMessage(error))
+    if (isCurrentMessageLoad(instanceId, sessionId, loadEpoch)) {
+      setSessionMessagesLoadError(instanceId, sessionId, getOpencodeErrorMessage(error, tGlobal("messageSection.loadError.detail")))
+    }
     throw error
   } finally {
-    setLoading((prev) => {
-      const next = { ...prev }
-      const loadingSet = next.loadingMessages.get(instanceId)
-      if (loadingSet) {
-        loadingSet.delete(sessionId)
-      }
-      return next
-    })
+    if (isCurrentMessageLoad(instanceId, sessionId, loadEpoch)) {
+      setLoading((prev) => {
+        const next = { ...prev }
+        const loadingSet = next.loadingMessages.get(instanceId)
+        if (loadingSet) loadingSet.delete(sessionId)
+        return next
+      })
+    }
   }
 
+  if (retryAfterRevisionConflict && sessions().get(instanceId)?.has(sessionId)) {
+    await new Promise((resolve) => setTimeout(resolve, 50))
+    return loadMessages(instanceId, sessionId, { force: true, skipChildren })
+  }
+
+  if (!isCurrentMessageLoad(instanceId, sessionId, loadEpoch) || !sessions().get(instanceId)?.has(sessionId)) return
   updateSessionInfo(instanceId, sessionId)
 
   if (!skipChildren && session.parentId === null) {
@@ -991,12 +1244,15 @@ async function loadMessages(
 export {
   createSession,
   deleteSession,
+  removeSessionRuntimeState,
   fetchAgents,
   fetchProviders,
 
   fetchSessions,
+  hydrateRestoredSessionChain,
   loadMoreSessions,
   searchSessions,
   forkSession,
   loadMessages,
+  clearSessionListRequestState,
 }
diff --git a/packages/ui/src/stores/session-events.ts b/packages/ui/src/stores/session-events.ts
index 1742e325..427579d0 100644
--- a/packages/ui/src/stores/session-events.ts
+++ b/packages/ui/src/stores/session-events.ts
@@ -16,6 +16,7 @@ import type {
 import type { MessageStatus } from "./message-v2/types"
 
 import { getLogger } from "../lib/logger"
+import type { EventSessionDeleted } from "../lib/sse-manager"
 import { requestData } from "../lib/opencode-api"
 import {
   enqueueDelta,
@@ -45,12 +46,12 @@ import { preferences } from "./preferences"
 import {
   instances,
   addPermissionToQueue,
+  getPermissionQueue,
   removePermissionFromQueue,
   markPermissionReplied,
   hasRepliedPermission,
   addQuestionToQueue,
   removeQuestionFromQueue,
-  drainAutoAcceptPermissionsForInstance,
 } from "./instances"
 import { showAlertDialog } from "./alerts"
 import {
@@ -62,12 +63,13 @@ import {
   type SessionRetryState,
   type SessionStatus,
 } from "../types/session"
-import { ensureSessionParentExpanded, prependSessionListId, sessions, setSessions, syncInstanceSessionIndicator, withSession } from "./session-state"
+import { ensureSessionAncestorsExpanded, getAuthoritativelyDeletedSessionIdsForInstance, prependSessionListId, sessions, setSessionStatus, setSessions, syncInstanceSessionIndicator, withSession } from "./session-state"
+import { mergeFetchedSessionRuntimeState } from "./session-generation-recovery"
 import { normalizeMessagePart } from "./message-v2/normalizers"
 import { updateSessionInfo } from "./message-v2/session-info"
 import { tGlobal } from "../lib/i18n"
 
-import { loadMessages } from "./session-api"
+import { loadMessages, removeSessionRuntimeState } from "./session-api"
 import { getRootClient } from "./opencode-client"
 import { getWorktreeSlugForDirectory, getWorktreeSlugForSession } from "./worktrees"
 import { getOpenCodeWorkspaceIdForWorktree } from "./opencode-workspaces"
@@ -94,14 +96,6 @@ const log = getLogger("sse")
 const pendingSessionFetches = new Map<string, Promise<void>>()
 let activeRetryToast: ToastHandle | null = null
 
-function isSameRetryState(left: SessionRetryState | null | undefined, right: SessionRetryState | null | undefined): boolean {
-  const a = left ?? null
-  const b = right ?? null
-  if (a === b) return true
-  if (!a || !b) return false
-  return a.attempt === b.attempt && a.message === b.message && a.next === b.next
-}
-
 function shouldSendOsNotification(kind: "needsInput" | "idle"): boolean {
   if (typeof document === "undefined") return false
   const pref = preferences()
@@ -165,34 +159,6 @@ interface TuiToastEvent {
 
 const ALLOWED_TOAST_VARIANTS = new Set<ToastVariant>(["info", "success", "warning", "error"])
 
-function applySessionStatus(instanceId: string, sessionId: string, status: SessionStatus, retry?: SessionRetryState | null) {
-  let parentToExpand: string | null = null
-
-  withSession(instanceId, sessionId, (session) => {
-    const current = session.status ?? "idle"
-    const nextRetry = retry ?? null
-    if (current === status && isSameRetryState(session.retry, nextRetry)) return false
-
-    if (current === "compacting" && status !== "compacting") {
-      return false
-    }
-
-    session.status = status
-    session.retry = status === "working" ? nextRetry : null
-    session.idleSince = getIdleSinceForStatusTransition(current, status, session.idleSince)
-
-    // Auto-expand the parent thread when a child session starts working.
-    // Users can still collapse it; we only expand on the transition.
-    if (session.parentId && status === "working" && current !== "working") {
-      parentToExpand = session.parentId
-    }
-  })
-
-  if (parentToExpand) {
-    ensureSessionParentExpanded(instanceId, parentToExpand)
-  }
-}
-
 async function fetchSessionInfo(instanceId: string, sessionId: string, directory?: string): Promise<Session | null> {
   const instance = instances().get(instanceId)
   if (!instance?.client) return null
@@ -208,73 +174,63 @@ async function fetchSessionInfo(instanceId: string, sessionId: string, directory
       "session.get",
     )
 
-    let fetchedStatus: SessionStatus = "idle"
-    let fetchedRetry: SessionRetryState | null = null
+    let rawStatus = (info as any)?.status
+    let fetchedStatusKnown = false
     try {
-      let statuses: Record<string, any> = {}
-      try {
-        statuses = await requestData<Record<string, any>>(client.session.status(), "session.status")
-      } catch {
-        statuses = await requestData<Record<string, any>>(client.session.status(), "session.status")
-      }
-      // Session status is global-ish; prefer the root context when available.
-      // (OpenCode may scope status by directory in older builds.)
-      // If root fails, fall back to the worktree-scoped client.
-      //
-      // Note: requestData throws on error, so we catch below.
-      const rawStatus = (info as any)?.status ?? statuses?.[sessionId]
-      const hasType = rawStatus && typeof rawStatus === "object" && typeof rawStatus.type === "string"
-      fetchedStatus = hasType ? mapSdkSessionStatus(rawStatus) : "idle"
-      fetchedRetry = hasType ? mapSdkSessionRetry(rawStatus) : null
+      const statuses = await requestData<Record<string, any>>(client.session.status(), "session.status")
+      rawStatus ??= statuses?.[sessionId]
+      fetchedStatusKnown = true
     } catch (error) {
       log.error("Failed to fetch session status", error)
     }
+    const hasStatus = rawStatus && typeof rawStatus === "object" && typeof rawStatus.type === "string"
+    fetchedStatusKnown ||= Boolean(hasStatus)
+    const fetchedStatus: SessionStatus = hasStatus ? mapSdkSessionStatus(rawStatus) : "idle"
+    const fetchedRetry: SessionRetryState | null = hasStatus ? mapSdkSessionRetry(rawStatus) : null
 
     const fetched = createClientSession(info, instanceId, "", { providerId: "", modelId: "" }, fetchedStatus)
     fetched.retry = fetchedRetry
+    fetched.runtimeStatusKnown = fetchedStatusKnown
 
     let updatedInstanceSessions: Map<string, Session> | undefined
-    let shouldExpandParent: string | null = null
-    let shouldDrainAutoAcceptPermissions = false
+    let shouldExpandAncestors = false
 
     setSessions((prev) => {
       const next = new Map(prev)
       const instanceSessions = next.get(instanceId) ?? new Map<string, Session>()
       const existing = instanceSessions.get(sessionId)
-      const merged: Session = {
+      const compacting = existing?.status === "compacting"
+      const candidate: Session = {
         ...fetched,
         agent: existing?.agent ?? fetched.agent,
         model: existing?.model ?? fetched.model,
-        status: existing?.status === "compacting" ? "compacting" : fetched.status,
-        retry: existing?.status === "compacting" ? null : fetched.retry,
-        idleSince: getIdleSinceForStatusTransition(
-          existing?.status,
-          existing?.status === "compacting" ? "compacting" : fetched.status,
-          existing?.idleSince,
-        ),
+        status: compacting ? "compacting" : fetched.status,
+        retry: compacting ? null : fetched.retry,
+        idleSince: getIdleSinceForStatusTransition(existing?.status, compacting ? "compacting" : fetched.status, existing?.idleSince),
         pendingPermission: existing?.pendingPermission ?? fetched.pendingPermission,
         pendingQuestion: existing?.pendingQuestion ?? false,
+        runtimeStatusKnown: compacting || fetched.runtimeStatusKnown,
       }
+      const merged = mergeFetchedSessionRuntimeState(
+        candidate,
+        existing,
+        existing,
+        getAuthoritativelyDeletedSessionIdsForInstance(instanceId).has(sessionId),
+      )
+      if (!merged) return prev
       instanceSessions.set(sessionId, merged)
       next.set(instanceId, instanceSessions)
       updatedInstanceSessions = instanceSessions
-      shouldDrainAutoAcceptPermissions = Boolean(merged.parentId)
 
       if (merged.parentId && merged.status === "working" && (existing?.status ?? "idle") !== "working") {
-        shouldExpandParent = merged.parentId
+        shouldExpandAncestors = true
       }
       return next
     })
 
     syncInstanceSessionIndicator(instanceId, updatedInstanceSessions)
 
-    if (shouldDrainAutoAcceptPermissions) {
-      drainAutoAcceptPermissionsForInstance(instanceId)
-    }
-
-    if (shouldExpandParent) {
-      ensureSessionParentExpanded(instanceId, shouldExpandParent)
-    }
+    if (shouldExpandAncestors) ensureSessionAncestorsExpanded(instanceId, sessionId)
 
     return fetched
   } catch (error) {
@@ -290,25 +246,19 @@ function ensureSessionStatus(
   directory?: string,
   retry?: SessionRetryState | null,
 ) {
-  const instanceSessions = sessions().get(instanceId)
-  const existing = instanceSessions?.get(sessionId)
+  const existing = sessions().get(instanceId)?.get(sessionId)
   if (existing) {
-    if ((existing.status ?? "idle") === status && isSameRetryState(existing.retry, retry)) {
-      return
-    }
-    applySessionStatus(instanceId, sessionId, status, retry)
+    setSessionStatus(instanceId, sessionId, status, { retry })
     return
   }
 
   const key = `${instanceId}:${sessionId}`
-  if (pendingSessionFetches.has(key)) {
-    return
-  }
+  if (pendingSessionFetches.has(key)) return
 
   const pending = (async () => {
     const fetched = await fetchSessionInfo(instanceId, sessionId, directory)
     if (!fetched) return
-    applySessionStatus(instanceId, sessionId, status, retry)
+    setSessionStatus(instanceId, sessionId, status, { retry })
   })()
 
   pendingSessionFetches.set(key, pending)
@@ -492,6 +442,7 @@ function handleSessionUpdate(instanceId: string, event: EventSessionUpdated): vo
   const info = event.properties?.info
 
   if (!info) return
+  if (getAuthoritativelyDeletedSessionIdsForInstance(instanceId).has(info.id)) return
 
   const instanceSessions = sessions().get(instanceId) ?? new Map<string, Session>()
 
@@ -542,9 +493,7 @@ function handleSessionUpdate(instanceId: string, event: EventSessionUpdated): vo
 
     syncInstanceSessionIndicator(instanceId, updatedInstanceSessions)
     setSessionRevertV2(instanceId, info.id, info.revert ?? null)
-    if (newSession.parentId) {
-      drainAutoAcceptPermissionsForInstance(instanceId)
-    } else {
+    if (!newSession.parentId) {
       prependSessionListId(instanceId, newSession.id)
     }
 
@@ -585,12 +534,18 @@ function handleSessionUpdate(instanceId: string, event: EventSessionUpdated): vo
 
     syncInstanceSessionIndicator(instanceId, updatedInstanceSessions)
     setSessionRevertV2(instanceId, info.id, info.revert ?? null)
-    if (updatedSession.parentId) {
-      drainAutoAcceptPermissionsForInstance(instanceId)
-    }
   }
 }
 
+function handleSessionDeleted(instanceId: string, event: EventSessionDeleted): void {
+  const properties = event.properties
+  const sessionId = properties?.info?.id ?? properties?.sessionID ?? properties?.id
+  if (!sessionId) return
+
+  log.info(`[SSE] Session deleted: ${sessionId}`)
+  removeSessionRuntimeState(instanceId, sessionId)
+}
+
 function handleSessionIdle(instanceId: string, event: EventSessionIdle): void {
   const sessionId = event.properties?.sessionID
   if (!sessionId) return
@@ -643,15 +598,8 @@ function handleSessionCompacted(instanceId: string, event: EventSessionCompacted
   log.info(`[SSE] Session compacted: ${sessionID}`)
 
   const existing = sessions().get(instanceId)?.get(sessionID)
-  if (existing) {
-    withSession(instanceId, sessionID, (session) => {
-      session.status = "working"
-      session.retry = null
-      session.idleSince = null
-    })
-  } else {
-    ensureSessionStatus(instanceId, sessionID, "working", (event as any)?.directory)
-  }
+  if (existing) setSessionStatus(instanceId, sessionID, "working", { force: true })
+  else ensureSessionStatus(instanceId, sessionID, "working", (event as any)?.directory)
 
   loadMessages(instanceId, sessionID, { force: true }).catch((error) => log.error("Failed to reload session after compaction", error))
 
@@ -695,7 +643,7 @@ function handleMessageRemoved(instanceId: string, event: MessageRemovedEvent): v
   if (!sessionID || !messageID) return
 
   log.info(`[SSE] Message removed from session ${sessionID}`, { messageID })
-  removeMessageV2(instanceId, messageID)
+  removeMessageV2(instanceId, messageID, sessionID)
   updateSessionInfo(instanceId, sessionID)
 }
 
@@ -704,7 +652,7 @@ function handleMessagePartRemoved(instanceId: string, event: MessagePartRemovedE
   if (!sessionID || !messageID || !partID) return
 
   log.info(`[SSE] Message part removed from session ${sessionID}`, { messageID, partID })
-  removeMessagePartV2(instanceId, messageID, partID)
+  removeMessagePartV2(instanceId, messageID, partID, sessionID)
   updateSessionInfo(instanceId, sessionID)
 }
 
@@ -728,12 +676,16 @@ function handleTuiToast(_instanceId: string, event: TuiToastEvent): void {
 function handlePermissionUpdated(instanceId: string, event: EventPermissionV2Asked | LegacyPermissionAskedEvent): void {
   const permission = event?.properties as PermissionRequest | undefined
   if (!permission) return
-  const source = event.type === "permission.v2.asked" ? "v2" : "legacy"
   const permissionId = getPermissionId(permission)
-  if (permissionId && hasRepliedPermission(instanceId, permissionId)) {
+  if (!permissionId) return
+  if (hasRepliedPermission(instanceId, permissionId)) {
     log.info(`[SSE] Ignoring stale permission request after local reply: ${permissionId}`)
     return
   }
+  const isPending = getPermissionQueue(instanceId).some((pending) => pending.id === permissionId)
+  const source = event.type === "permission.v2.asked"
+    ? "v2"
+    : event.type === "permission.updated" && isPending ? undefined : "legacy"
 
   log.info(`[SSE] Permission request: ${permissionId} (${getPermissionKind(permission)})`)
   const queuedPermission = addPermissionToQueue(instanceId, permission, source) ?? permission
@@ -802,6 +754,7 @@ export {
   handleQuestionAsked,
   handleQuestionAnswered,
   handleSessionCompacted,
+  handleSessionDeleted,
   handleSessionError,
   handleSessionIdle,
   handleSessionStatus,
diff --git a/packages/ui/src/stores/session-generation-admission.test.ts b/packages/ui/src/stores/session-generation-admission.test.ts
new file mode 100644
index 00000000..521ad740
--- /dev/null
+++ b/packages/ui/src/stores/session-generation-admission.test.ts
@@ -0,0 +1,38 @@
+import assert from "node:assert/strict"
+import { afterEach, describe, it } from "node:test"
+import type { Session } from "../types/session.ts"
+import { beginSessionGenerationAdmission, getSessions, setSessions, setSessionStatus } from "./session-state.ts"
+const instanceId = "generation-admission-instance"
+const sessionId = "generation-admission-session"
+const seedSession = () => setSessions(new Map([[instanceId, new Map([[sessionId, {
+  id: sessionId, instanceId, parentId: null, title: "Session", agent: "build",
+  model: { providerId: "provider", modelId: "model" }, version: "1", time: { created: 1, updated: 1 },
+  status: "idle", idleSince: 10, runtimeStatusKnown: true, generationRecovery: "interrupted",
+} as Session]])]]))
+const result = () => {
+  const { status, runtimeStatusKnown, generationRecovery, generationAdmissionToken: token } = getSessions(instanceId)[0]
+  return { status, runtimeStatusKnown, generationRecovery, token }
+}
+afterEach(() => setSessions(new Map()))
+describe("session generation admission", () => {
+  const admit = () => beginSessionGenerationAdmission(instanceId, sessionId)
+  const cases = [
+    ["newer authoritative working status supersedes completion", () => { const admission = admit(); setSessionStatus(instanceId, sessionId, "working"); admission.complete() }, { status: "working", runtimeStatusKnown: true, generationRecovery: null, token: undefined }],
+    ["idle authority waits for admission acknowledgement", () => {
+      const admission = admit(); setSessionStatus(instanceId, sessionId, "idle")
+      assert.deepEqual(result(), { status: "idle", runtimeStatusKnown: false, generationRecovery: "pending", token: result().token })
+      assert.equal(typeof result().token, "number")
+      admission.complete()
+    }, { status: "idle", runtimeStatusKnown: false, generationRecovery: "pending", token: undefined }],
+    ["rollback restores interrupted state without newer authority", () => admit().rollback(), { status: "idle", runtimeStatusKnown: true, generationRecovery: "interrupted", token: undefined }],
+    ["one successful overlapping admission retains pending recovery", () => { const first = admit(); const second = admit(); first.complete(); second.rollback() }, { status: "idle", runtimeStatusKnown: false, generationRecovery: "pending", token: undefined }],
+  ] as const
+  for (const [label, run, expected] of cases) {
+    it(label, () => {
+      seedSession()
+      run()
+      assert.deepEqual(result(), expected)
+      if (expected.generationRecovery === "interrupted") assert.equal(getSessions(instanceId)[0].idleSince, 10)
+    })
+  }
+})
diff --git a/packages/ui/src/stores/session-generation-recovery.test.ts b/packages/ui/src/stores/session-generation-recovery.test.ts
new file mode 100644
index 00000000..ec5e3988
--- /dev/null
+++ b/packages/ui/src/stores/session-generation-recovery.test.ts
@@ -0,0 +1,77 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import type { Session } from "../types/session.ts"
+import { getPersistedGenerationRecovery, mergeFetchedSessionRuntimeState, resolveAuthoritativeGenerationRecovery, resolveHydratedGenerationRecovery } from "./session-generation-recovery.ts"
+const session = (state: Partial<Session> = {}): Session => ({
+  id: "session", instanceId: "instance", parentId: null, title: "Session", agent: "build",
+  model: { providerId: "provider", modelId: "model" }, version: "1",
+  time: { created: 1, updated: 1 }, status: "idle", ...state,
+} as Session)
+const runtime = (value: Session) => ({
+  title: value.title, status: value.status, runtimeStatusKnown: value.runtimeStatusKnown,
+  generationRecovery: value.generationRecovery, token: value.generationAdmissionToken, source: value.metadata?.source, updated: value.time.updated,
+})
+describe("session generation recovery", () => {
+  it("resolves hydrated, authoritative, and persisted recovery states", () => {
+    const cases: Array<[string, () => unknown, unknown]> = [
+      ["working reconnect", () => resolveHydratedGenerationRecovery("working", "working", true), null],
+      ["compacting reconnect", () => resolveHydratedGenerationRecovery("working", "compacting", true), null],
+      ["idle before authority", () => resolveHydratedGenerationRecovery("working", "idle", false), "pending"],
+      ["authoritative idle hydration", () => resolveHydratedGenerationRecovery("working", "idle", true), "interrupted"],
+      ["authoritative idle event", () => resolveAuthoritativeGenerationRecovery("pending", "idle"), "interrupted"],
+      ["interruption survives hydration", () => resolveHydratedGenerationRecovery("interrupted", "idle", false), "interrupted"],
+      ["interruption persists", () => getPersistedGenerationRecovery("idle", "interrupted"), "interrupted"],
+      ["working clears pending", () => resolveAuthoritativeGenerationRecovery("pending", "working"), null],
+      ["working clears interruption", () => resolveAuthoritativeGenerationRecovery("interrupted", "working"), null],
+      ["working persists", () => getPersistedGenerationRecovery("working", null), "working"],
+      ["compacting persists", () => getPersistedGenerationRecovery("compacting", null), "working"],
+      ["pending persists as work", () => getPersistedGenerationRecovery("idle", "pending"), "working"],
+      ["ordinary idle omitted", () => getPersistedGenerationRecovery("idle", null), null],
+    ]
+    for (const [label, actual, expected] of cases) assert.equal(actual(), expected, label)
+  })
+  const mergeCases = [
+    ["newer SSE state supersedes a stale fetch", {
+      captured: session({ title: "Captured", runtimeStatusKnown: false }),
+      fetched: session({ title: "Stale fetch", metadata: { source: "fetch" }, time: { created: 1, updated: 2 }, runtimeStatusKnown: true, generationRecovery: "interrupted" }),
+      latest: session({ title: "New SSE title", metadata: { source: "sse" }, time: { created: 1, updated: 3 }, status: "working", runtimeStatusKnown: true, generationRecovery: null }),
+      expected: { title: "New SSE title", status: "working", runtimeStatusKnown: true, generationRecovery: null, token: undefined, source: "sse", updated: 3 },
+    }],
+    ["in-flight admission survives a fetch snapshot", {
+      captured: session({ runtimeStatusKnown: false, generationRecovery: "pending", generationAdmissionToken: 1 }),
+      fetched: session({ runtimeStatusKnown: true, generationRecovery: "interrupted" }),
+      latest: null,
+      expected: { title: "Session", status: "idle", runtimeStatusKnown: false, generationRecovery: "pending", token: 1, source: undefined, updated: 1 },
+    }],
+    ["active fetch wins after a captured admission completes", {
+      captured: session({ title: "Captured", runtimeStatusKnown: true, generationRecovery: "interrupted" }),
+      fetched: session({ title: "Fetched", status: "working", runtimeStatusKnown: true, generationRecovery: null }),
+      latest: session({ title: "New SSE title", metadata: { source: "sse" }, time: { created: 1, updated: 3 }, runtimeStatusKnown: false, generationRecovery: "pending" }),
+      expected: { title: "New SSE title", status: "working", runtimeStatusKnown: true, generationRecovery: null, token: undefined, source: "sse", updated: 3 },
+    }],
+    ["active authority clears a captured admission token", {
+      captured: session({ runtimeStatusKnown: false, generationRecovery: "pending", generationAdmissionToken: 1 }),
+      fetched: session({ status: "working", runtimeStatusKnown: true, generationRecovery: null }),
+      latest: session({ runtimeStatusKnown: false, generationRecovery: "pending", generationAdmissionToken: undefined }),
+      expected: { title: "Session", status: "working", runtimeStatusKnown: true, generationRecovery: null, token: undefined, source: undefined, updated: 1 },
+    }],
+    ["newer local state preserves optional field deletion", {
+      captured: session({ retry: { attempt: 1, message: "retrying", next: 10 } }),
+      fetched: session({ retry: { attempt: 2, message: "stale", next: 20 } }),
+      latest: session(),
+      expected: { title: "Session", status: "idle", runtimeStatusKnown: undefined, generationRecovery: undefined, token: undefined, source: undefined, updated: 1 },
+    }],
+  ] as const
+  for (const [label, test] of mergeCases) {
+    it(label, () => {
+      const merged = mergeFetchedSessionRuntimeState(test.fetched, test.captured, test.latest ?? test.captured)
+      assert.ok(merged)
+      assert.deepEqual(runtime(merged), test.expected)
+    })
+  }
+  it("does not resurrect a session deleted while its fetch was pending", () => {
+    const fetched = session()
+    assert.equal(mergeFetchedSessionRuntimeState(fetched, session(), undefined), null)
+    assert.equal(mergeFetchedSessionRuntimeState(fetched, undefined, undefined, true), null)
+  })
+})
diff --git a/packages/ui/src/stores/session-generation-recovery.ts b/packages/ui/src/stores/session-generation-recovery.ts
new file mode 100644
index 00000000..e0a767eb
--- /dev/null
+++ b/packages/ui/src/stores/session-generation-recovery.ts
@@ -0,0 +1,63 @@
+import type { Session, SessionStatus } from "../types/session"
+
+export type GenerationRecoveryState = "pending" | "interrupted"
+export type PersistedGenerationRecovery = "working" | "interrupted"
+
+export function resolveHydratedGenerationRecovery(
+  persisted: PersistedGenerationRecovery,
+  runtimeStatus: SessionStatus,
+  runtimeStatusKnown: boolean,
+): GenerationRecoveryState | null {
+  if (runtimeStatus === "working" || runtimeStatus === "compacting") return null
+  if (persisted === "interrupted") return "interrupted"
+  return runtimeStatusKnown ? "interrupted" : "pending"
+}
+
+export function resolveAuthoritativeGenerationRecovery(
+  current: GenerationRecoveryState | null | undefined,
+  status: SessionStatus,
+): GenerationRecoveryState | null {
+  if (status === "working" || status === "compacting") return null
+  return current === "pending" ? "interrupted" : current ?? null
+}
+
+export function getPersistedGenerationRecovery(
+  status: SessionStatus,
+  recovery: GenerationRecoveryState | null | undefined,
+): PersistedGenerationRecovery | null {
+  if (status === "working" || status === "compacting" || recovery === "pending") return "working"
+  return recovery === "interrupted" ? "interrupted" : null
+}
+
+export function mergeFetchedSessionRuntimeState(
+  fetched: Session,
+  captured: Session | undefined,
+  latest: Session | undefined,
+  deleted = false,
+): Session | null {
+  if (deleted) return null
+  if (captured && !latest) return null
+  if (!latest) return fetched
+  if (latest === captured) {
+    return latest.generationAdmissionToken === undefined ? fetched : { ...fetched, ...latest }
+  }
+  const merged = { ...fetched }
+  const keys = new Set<keyof Session>([
+    ...(Object.keys(captured ?? {}) as (keyof Session)[]),
+    ...(Object.keys(latest) as (keyof Session)[]),
+  ])
+  for (const key of keys) {
+    if (captured && Object.is(captured[key], latest[key])) continue
+    if (Object.prototype.hasOwnProperty.call(latest, key)) (merged as any)[key] = latest[key]
+    else delete (merged as any)[key]
+  }
+
+  const fetchedActive = fetched.status === "working" || fetched.status === "compacting"
+  if (captured && fetchedActive && latest.generationAdmissionToken === undefined
+    && latest.runtimeStatusKnown === false && latest.generationRecovery === "pending") {
+    for (const key of ["status", "runtimeStatusKnown", "generationRecovery", "generationAdmissionToken", "retry", "idleSince"] as const) {
+      (merged as any)[key] = fetched[key]
+    }
+  }
+  return merged
+}
diff --git a/packages/ui/src/stores/session-list-options.ts b/packages/ui/src/stores/session-list-options.ts
index 91bc27c3..fccbee6a 100644
--- a/packages/ui/src/stores/session-list-options.ts
+++ b/packages/ui/src/stores/session-list-options.ts
@@ -1,4 +1,4 @@
-export const PROJECT_SESSION_LIST_LIMIT = 1000
+export const PROJECT_SESSION_LIST_LIMIT = 10000
 
 type ProjectSessionListInput = {
   directory?: string
@@ -10,6 +10,21 @@ export type ProjectSessionListOptions = ProjectSessionListInput & {
   scope: "project"
 }
 
+type SessionDirectorySource = {
+  directory?: string | null
+}
+
+function normalizeSessionDirectory(directory: string | null | undefined): string {
+  const trimmed = directory?.trim()
+  if (!trimmed) return ""
+
+  const slashNormalized = trimmed.replace(/\\/g, "/").replace(/\/+$/, "")
+  const comparable = slashNormalized || "/"
+  const isWindowsPath = /^[A-Za-z]:\//.test(comparable) || comparable.startsWith("//") || trimmed.includes("\\")
+
+  return isWindowsPath ? comparable.toLowerCase() : comparable
+}
+
 export function buildProjectSessionListOptions(options: ProjectSessionListInput): ProjectSessionListOptions {
   return {
     ...(options.directory ? { directory: options.directory } : {}),
@@ -18,3 +33,30 @@ export function buildProjectSessionListOptions(options: ProjectSessionListInput)
     scope: "project",
   }
 }
+
+export function isProjectSessionListComplete(resultCount: number): boolean {
+  return resultCount < PROJECT_SESSION_LIST_LIMIT
+}
+
+export function filterProjectScopedSessions<T extends SessionDirectorySource>(
+  sessions: T[],
+  allowedDirectories: Array<string | null | undefined>,
+): T[] {
+  const allowed = new Set(allowedDirectories.map(normalizeSessionDirectory).filter(Boolean))
+  if (allowed.size === 0) return sessions
+
+  return sessions.filter((session) => {
+    const directory = normalizeSessionDirectory(session.directory)
+    return !directory || allowed.has(directory)
+  })
+}
+
+export function getAuthoritativelyMissingSessionIds(
+  existingIds: Iterable<string>,
+  listedIds: Iterable<string>,
+  complete: boolean,
+): string[] {
+  if (!complete) return []
+  const listed = new Set(listedIds)
+  return Array.from(existingIds).filter((id) => !listed.has(id))
+}
diff --git a/packages/ui/src/stores/session-metadata-completeness.ts b/packages/ui/src/stores/session-metadata-completeness.ts
new file mode 100644
index 00000000..922c52e0
--- /dev/null
+++ b/packages/ui/src/stores/session-metadata-completeness.ts
@@ -0,0 +1,7 @@
+export const shouldReplaceSessionMetadata = (current: Record<string, unknown> | undefined): boolean =>
+  current === undefined || Object.keys(current).length === 0
+
+export const preferSessionMetadata = (
+  incoming: Record<string, unknown> | undefined,
+  existing: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined => shouldReplaceSessionMetadata(incoming) ? existing ?? incoming : incoming
diff --git a/packages/ui/src/stores/session-metadata.test.ts b/packages/ui/src/stores/session-metadata.test.ts
new file mode 100644
index 00000000..8843703a
--- /dev/null
+++ b/packages/ui/src/stores/session-metadata.test.ts
@@ -0,0 +1,18 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { preferSessionMetadata, shouldReplaceSessionMetadata } from "./session-metadata-completeness.ts"
+
+describe("session metadata hydration", () => {
+  it("treats missing and empty list metadata as incomplete", () => {
+    assert.equal(shouldReplaceSessionMetadata(undefined), true)
+    assert.equal(shouldReplaceSessionMetadata({}), true)
+  })
+
+  it("preserves metadata and tags populated while detailed hydration is pending", () => {
+    assert.equal(shouldReplaceSessionMetadata({ tags: ["live"] }), false)
+    assert.equal(shouldReplaceSessionMetadata({ owner: "opencode" }), false)
+    assert.deepEqual(preferSessionMetadata({}, { tags: ["hydrated"] }), { tags: ["hydrated"] })
+    assert.deepEqual(preferSessionMetadata({ tags: ["fresh"] }, { tags: ["old"] }), { tags: ["fresh"] })
+  })
+})
diff --git a/packages/ui/src/stores/session-metadata.ts b/packages/ui/src/stores/session-metadata.ts
index 15ba37b6..bd4f4ab8 100644
--- a/packages/ui/src/stores/session-metadata.ts
+++ b/packages/ui/src/stores/session-metadata.ts
@@ -1,6 +1,8 @@
 import type { OpencodeClient } from "@opencode-ai/sdk/v2/client"
+import { serverApi } from "../lib/api-client"
 import { requestData } from "../lib/opencode-api"
 import { sessions, withSession } from "./session-state"
+import { shouldReplaceSessionMetadata } from "./session-metadata-completeness"
 
 const CODENOMAD_METADATA_KEY = "codenomad"
 const CODENOMAD_METADATA_VERSION = 1
@@ -29,30 +31,6 @@ function normalizeCodeNomadMetadata(value: unknown): CodeNomadSessionMetadata {
   return metadata
 }
 
-function mergeCodeNomadMetadata(
-  metadata: MetadataRecord,
-  updater: (current: CodeNomadSessionMetadata) => CodeNomadSessionMetadata,
-): MetadataRecord {
-  const currentCodeNomad = isRecord(metadata[CODENOMAD_METADATA_KEY])
-    ? { ...(metadata[CODENOMAD_METADATA_KEY] as MetadataRecord) }
-    : {}
-  const nextCodeNomad = updater(normalizeCodeNomadMetadata(currentCodeNomad))
-  const mergedCodeNomad: MetadataRecord = {
-    ...currentCodeNomad,
-    ...nextCodeNomad,
-    version: CODENOMAD_METADATA_VERSION,
-  }
-
-  if (!nextCodeNomad.worktreeSlug) {
-    delete mergedCodeNomad.worktreeSlug
-  }
-
-  return {
-    ...metadata,
-    [CODENOMAD_METADATA_KEY]: mergedCodeNomad,
-  }
-}
-
 export function getSessionMetadata(instanceId: string, sessionId: string): MetadataRecord {
   return normalizeMetadata(sessions().get(instanceId)?.get(sessionId)?.metadata)
 }
@@ -61,62 +39,31 @@ export function getCodeNomadSessionMetadata(instanceId: string, sessionId: strin
   return normalizeCodeNomadMetadata(getSessionMetadata(instanceId, sessionId)[CODENOMAD_METADATA_KEY])
 }
 
-export async function updateSessionMetadataWithClient(
-  client: OpencodeClient,
-  instanceId: string,
-  sessionId: string,
-  updater: (metadata: MetadataRecord) => MetadataRecord,
-): Promise<MetadataRecord> {
-  const latest = await requestData<any>(client.session.get({ sessionID: sessionId }), "session.get")
-  const nextMetadata = updater(normalizeMetadata(latest?.metadata))
-  const updated = await requestData<any>(
-    client.session.update({ sessionID: sessionId, metadata: nextMetadata } as any),
-    "session.update",
-  )
-  const persistedMetadata = normalizeMetadata(updated?.metadata ?? nextMetadata)
-
-  withSession(instanceId, sessionId, (session) => {
-    session.metadata = persistedMetadata
-  })
-
-  return persistedMetadata
-}
-
 export async function hydrateSessionMetadataWithClient(
   client: OpencodeClient,
   instanceId: string,
   sessionId: string,
+  query?: { workspace?: string },
 ): Promise<MetadataRecord> {
-  const latest = await requestData<any>(client.session.get({ sessionID: sessionId }), "session.get")
+  const expectedMetadata = sessions().get(instanceId)?.get(sessionId)?.metadata
+  const latest = await requestData<any>(client.session.get({ sessionID: sessionId, ...query }), "session.get")
   const metadata = normalizeMetadata(latest?.metadata)
 
   withSession(instanceId, sessionId, (session) => {
+    if (session.metadata !== expectedMetadata || !shouldReplaceSessionMetadata(session.metadata)) return false
     session.metadata = metadata
   })
 
   return metadata
 }
 
-export async function updateCodeNomadSessionMetadataWithClient(
-  client: OpencodeClient,
-  instanceId: string,
-  sessionId: string,
-  updater: (metadata: CodeNomadSessionMetadata) => CodeNomadSessionMetadata,
-): Promise<CodeNomadSessionMetadata> {
-  const persisted = await updateSessionMetadataWithClient(client, instanceId, sessionId, (metadata) =>
-    mergeCodeNomadMetadata(metadata, updater),
-  )
-  return normalizeCodeNomadMetadata(persisted[CODENOMAD_METADATA_KEY])
-}
-
-export async function setSessionWorktreeSlugWithClient(
-  client: OpencodeClient,
+export async function setSessionWorktreeSlug(
   instanceId: string,
   sessionId: string,
   worktreeSlug: string,
 ): Promise<void> {
-  await updateCodeNomadSessionMetadataWithClient(client, instanceId, sessionId, (metadata) => ({
-    ...metadata,
-    worktreeSlug,
-  }))
+  const { metadata } = await serverApi.setSessionWorktreeSlug(instanceId, sessionId, worktreeSlug)
+  withSession(instanceId, sessionId, (session) => {
+    session.metadata = normalizeMetadata(metadata)
+  })
 }
diff --git a/packages/ui/src/stores/session-pagination.test.ts b/packages/ui/src/stores/session-pagination.test.ts
index 60580742..7ce69377 100644
--- a/packages/ui/src/stores/session-pagination.test.ts
+++ b/packages/ui/src/stores/session-pagination.test.ts
@@ -2,7 +2,13 @@ import assert from "node:assert/strict"
 import { describe, it } from "node:test"
 
 import { applySessionPage, getDefaultSessionPaginationState } from "./session-pagination-model.ts"
-import { PROJECT_SESSION_LIST_LIMIT, buildProjectSessionListOptions } from "./session-list-options.ts"
+import {
+  PROJECT_SESSION_LIST_LIMIT,
+  buildProjectSessionListOptions,
+  filterProjectScopedSessions,
+  getAuthoritativelyMissingSessionIds,
+  isProjectSessionListComplete,
+} from "./session-list-options.ts"
 
 describe("project session list loading", () => {
   it("builds a one-shot project-scoped request without pagination params", () => {
@@ -18,6 +24,35 @@ describe("project session list loading", () => {
     assert.equal("cursor" in options, false)
   })
 
+  it("filters project-scoped results to the root and known worktree directories", () => {
+    const sessions = [
+      { id: "root", directory: "/repo" },
+      { id: "worktree", directory: "/repo/.codenomad/worktrees/feature" },
+      { id: "sibling", directory: "/other" },
+      { id: "unknown" },
+    ]
+
+    assert.deepEqual(
+      filterProjectScopedSessions(sessions, ["/repo", "/repo/.codenomad/worktrees/feature"]).map((session) => session.id),
+      ["root", "worktree", "unknown"],
+    )
+  })
+
+  it("normalizes Windows paths when filtering project-scoped results", () => {
+    const sessions = [
+      { id: "root", directory: String.raw`C:\Repo` },
+      { id: "worktree", directory: "c:/repo/.codenomad/worktrees/feature/" },
+      { id: "other", directory: String.raw`C:\Other` },
+    ]
+
+    assert.deepEqual(
+      filterProjectScopedSessions(sessions, ["c:/repo/", String.raw`C:\Repo\.codenomad\worktrees\feature`]).map(
+        (session) => session.id,
+      ),
+      ["root", "worktree"],
+    )
+  })
+
   it("marks the loaded session list complete because the API does not paginate", () => {
     const state = applySessionPage(getDefaultSessionPaginationState(), ["root-1", "root-2"], false, true)
 
@@ -34,4 +69,18 @@ describe("project session list loading", () => {
     assert.equal(next.hasMore, false)
     assert.equal(next.nextCursor, undefined)
   })
+
+  it("reconciles sessions deleted while disconnected only from a complete refresh", () => {
+    const existing = ["retained", "outside-current-worktree", "deleted-remotely"]
+    const listed = ["retained", "outside-current-worktree"]
+
+    assert.deepEqual(getAuthoritativelyMissingSessionIds(existing, listed, true), ["deleted-remotely"])
+    assert.equal(isProjectSessionListComplete(PROJECT_SESSION_LIST_LIMIT - 1), true)
+    assert.equal(isProjectSessionListComplete(PROJECT_SESSION_LIST_LIMIT), false)
+    assert.deepEqual(
+      getAuthoritativelyMissingSessionIds(existing, listed, false),
+      [],
+      "a result capped at the request limit may be truncated",
+    )
+  })
 })
diff --git a/packages/ui/src/stores/session-pending-state.test.ts b/packages/ui/src/stores/session-pending-state.test.ts
new file mode 100644
index 00000000..bacb1791
--- /dev/null
+++ b/packages/ui/src/stores/session-pending-state.test.ts
@@ -0,0 +1,40 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { applySessionPendingState } from "./session-pending-state.ts"
+
+describe("applySessionPendingState", () => {
+  it("reconciles interruptions that arrived before sessions", () => {
+    const sessions = new Map([
+      ["permission", { id: "permission" }],
+      ["question", { id: "question" }],
+      ["idle", { id: "idle", pendingPermission: true }],
+    ])
+
+    const result = applySessionPendingState(sessions, new Set(["permission"]), new Set(["question"]))
+
+    assert.deepEqual(result.get("permission"), {
+      id: "permission",
+      pendingPermission: true,
+      pendingQuestion: false,
+    })
+    assert.deepEqual(result.get("question"), {
+      id: "question",
+      pendingPermission: false,
+      pendingQuestion: true,
+    })
+    assert.deepEqual(result.get("idle"), {
+      id: "idle",
+      pendingPermission: false,
+      pendingQuestion: false,
+    })
+  })
+
+  it("preserves the map when pending state already matches", () => {
+    const sessions = new Map([
+      ["session", { id: "session", pendingPermission: true, pendingQuestion: false }],
+    ])
+
+    assert.equal(applySessionPendingState(sessions, new Set(["session"]), new Set()), sessions)
+  })
+})
diff --git a/packages/ui/src/stores/session-pending-state.ts b/packages/ui/src/stores/session-pending-state.ts
new file mode 100644
index 00000000..10413f9f
--- /dev/null
+++ b/packages/ui/src/stores/session-pending-state.ts
@@ -0,0 +1,24 @@
+type SessionPendingState = {
+  id: string
+  pendingPermission?: boolean
+  pendingQuestion?: boolean
+}
+
+export function applySessionPendingState<T extends SessionPendingState>(
+  sessions: Map<string, T>,
+  permissionSessionIds: ReadonlySet<string>,
+  questionSessionIds: ReadonlySet<string>,
+): Map<string, T> {
+  let next = sessions
+
+  for (const [sessionId, session] of sessions) {
+    const pendingPermission = permissionSessionIds.has(sessionId)
+    const pendingQuestion = questionSessionIds.has(sessionId)
+    if (session.pendingPermission === pendingPermission && session.pendingQuestion === pendingQuestion) continue
+
+    if (next === sessions) next = new Map(sessions)
+    next.set(sessionId, { ...session, pendingPermission, pendingQuestion })
+  }
+
+  return next
+}
diff --git a/packages/ui/src/stores/session-request-authority.test.ts b/packages/ui/src/stores/session-request-authority.test.ts
new file mode 100644
index 00000000..99bfeb78
--- /dev/null
+++ b/packages/ui/src/stores/session-request-authority.test.ts
@@ -0,0 +1,179 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { sdkManager } from "../lib/sdk-manager.ts"
+import type { Session } from "../types/session.ts"
+import { addInstance, removeInstance } from "./instances.ts"
+import { messageStoreBus } from "./message-v2/bus.ts"
+import { loadMessages, removeSessionRuntimeState, searchSessions } from "./session-api.ts"
+import {
+  clearInstanceDeletedSessionAuthority,
+  getSessionSearchResultIds,
+  invalidateSessionMessageLoad,
+  loading,
+  messagesLoaded,
+  sessions,
+  setSessions,
+} from "./session-state.ts"
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((done) => { resolve = done })
+  return { promise, resolve }
+}
+
+function session(instanceId: string, id: string, parentId: string | null = null): Session {
+  return {
+    id, instanceId, parentId, title: id, agent: "build", model: { providerId: "provider", modelId: "model" },
+    status: "idle", retry: null, idleSince: null, generationRecovery: null, runtimeStatusKnown: true,
+    version: "1", time: { created: 1, updated: 1 },
+  }
+}
+
+function apiSession(id: string, parentID?: string) {
+  return { id, parentID, title: id, version: "1", time: { created: 1, updated: 1 } }
+}
+
+function apiMessage(id: string, sessionId: string) {
+  return {
+    info: {
+      id, sessionID: sessionId, role: "assistant", agent: "build", providerID: "provider", modelID: "model",
+      time: { created: 1 },
+    },
+    parts: [],
+  }
+}
+
+function setup(instanceId: string) {
+  const client = { session: {} } as any
+  ;(sdkManager as any).clients.set(`${instanceId}:/workspaces/${instanceId}/instance`, client)
+  addInstance({ id: instanceId, folder: "/work", port: 0, pid: 0, proxyPath: "", status: "ready", client })
+  return {
+    client,
+    cleanup() {
+      messageStoreBus.unregisterInstance(instanceId)
+      setSessions((prev) => { const next = new Map(prev); next.delete(instanceId); return next })
+      clearInstanceDeletedSessionAuthority(instanceId)
+      removeInstance(instanceId, { authoritative: false })
+      sdkManager.destroyClientsForInstance(instanceId)
+    },
+  }
+}
+
+describe("session request authority", () => {
+  it("does not restore deleted search results or their parent chain", async () => {
+    const instanceId = "late-search-delete"
+    const { client, cleanup } = setup(instanceId)
+    const search = deferred<any>()
+    const parents = deferred<any>()
+    let calls = 0
+    ;(client.session as any).list = () => (++calls === 1 ? search.promise : parents.promise)
+
+    try {
+      const request = searchSessions(instanceId, "child")
+      search.resolve({ data: [apiSession("child", "parent")] })
+      await new Promise<void>((resolve) => setImmediate(resolve))
+      removeSessionRuntimeState(instanceId, "child")
+      removeSessionRuntimeState(instanceId, "parent")
+      parents.resolve({ data: [apiSession("parent")] })
+      await request
+
+      assert.equal(sessions().get(instanceId)?.has("child") ?? false, false)
+      assert.equal(sessions().get(instanceId)?.has("parent") ?? false, false)
+      assert.deepEqual(getSessionSearchResultIds(instanceId), [])
+    } finally {
+      cleanup()
+    }
+  })
+
+  it("does not hydrate messages after definitive deletion", async () => {
+    const instanceId = "late-message-delete", sessionId = "session"
+    const { client, cleanup } = setup(instanceId)
+    const response = deferred<any>()
+    ;(client.session as any).messages = () => response.promise
+    setSessions((prev) => new Map(prev).set(instanceId, new Map([[sessionId, session(instanceId, sessionId)]])))
+
+    try {
+      const request = loadMessages(instanceId, sessionId)
+      removeSessionRuntimeState(instanceId, sessionId)
+      response.resolve({ data: [apiMessage("deleted-message", sessionId)] })
+      await request
+
+      assert.deepEqual(messageStoreBus.getOrCreate(instanceId).getSessionMessageIds(sessionId), [])
+      assert.equal(messagesLoaded().get(instanceId)?.has(sessionId) ?? false, false)
+    } finally {
+      cleanup()
+    }
+  })
+
+  it("does not hydrate messages after cache eviction", async () => {
+    const instanceId = "late-message-eviction", sessionId = "session"
+    const { client, cleanup } = setup(instanceId)
+    const response = deferred<any>()
+    ;(client.session as any).messages = () => response.promise
+    setSessions((prev) => new Map(prev).set(instanceId, new Map([[sessionId, session(instanceId, sessionId)]])))
+
+    try {
+      const request = loadMessages(instanceId, sessionId)
+      invalidateSessionMessageLoad(instanceId, sessionId)
+      response.resolve({ data: [apiMessage("evicted-message", sessionId)] })
+      await request
+
+      assert.deepEqual(messageStoreBus.getOrCreate(instanceId).getSessionMessageIds(sessionId), [])
+      assert.equal(messagesLoaded().get(instanceId)?.has(sessionId) ?? false, false)
+    } finally {
+      cleanup()
+    }
+  })
+
+  it("does not reuse message load authority after an instance reopens", async () => {
+    const instanceId = "reopened-message-load", sessionId = "session"
+    const { client, cleanup } = setup(instanceId)
+    const oldResponse = deferred<any>()
+    const newResponse = deferred<any>()
+    let calls = 0
+    ;(client.session as any).messages = () => (++calls === 1 ? oldResponse.promise : newResponse.promise)
+    setSessions((prev) => new Map(prev).set(instanceId, new Map([[sessionId, session(instanceId, sessionId)]])))
+
+    try {
+      const oldRequest = loadMessages(instanceId, sessionId)
+      removeInstance(instanceId, { authoritative: false })
+      addInstance({ id: instanceId, folder: "/work", port: 0, pid: 0, proxyPath: "", status: "ready", client })
+      setSessions((prev) => new Map(prev).set(instanceId, new Map([[sessionId, session(instanceId, sessionId)]])))
+      const newRequest = loadMessages(instanceId, sessionId, { force: true })
+
+      oldResponse.resolve({ data: [apiMessage("old-message", sessionId)] })
+      await oldRequest
+      newResponse.resolve({ data: [apiMessage("new-message", sessionId)] })
+      await newRequest
+
+      assert.deepEqual(messageStoreBus.getOrCreate(instanceId).getSessionMessageIds(sessionId), ["new-message"])
+    } finally {
+      cleanup()
+    }
+  })
+
+  it("keeps a newer load authoritative when an older request finishes last", async () => {
+    const instanceId = "newer-message-load", sessionId = "session"
+    const { client, cleanup } = setup(instanceId)
+    const oldResponse = deferred<any>()
+    const newResponse = deferred<any>()
+    let calls = 0
+    ;(client.session as any).messages = () => (++calls === 1 ? oldResponse.promise : newResponse.promise)
+    setSessions((prev) => new Map(prev).set(instanceId, new Map([[sessionId, session(instanceId, sessionId)]])))
+
+    try {
+      const oldRequest = loadMessages(instanceId, sessionId)
+      const newRequest = loadMessages(instanceId, sessionId, { force: true })
+      newResponse.resolve({ data: [apiMessage("new-message", sessionId)] })
+      await newRequest
+      oldResponse.resolve({ data: [apiMessage("old-message", sessionId)] })
+      await oldRequest
+
+      assert.deepEqual(messageStoreBus.getOrCreate(instanceId).getSessionMessageIds(sessionId), ["new-message"])
+      assert.equal(loading().loadingMessages.get(instanceId)?.has(sessionId) ?? false, false)
+    } finally {
+      cleanup()
+    }
+  })
+})
diff --git a/packages/ui/src/stores/session-state.ts b/packages/ui/src/stores/session-state.ts
index eb9cf36a..e9cf30bd 100644
--- a/packages/ui/src/stores/session-state.ts
+++ b/packages/ui/src/stores/session-state.ts
@@ -1,10 +1,10 @@
 import { batch, createSignal } from "solid-js"
 
-import { getIdleSinceForStatusTransition, type Session, type SessionStatus, type Agent, type Provider } from "../types/session"
+import { getIdleSinceForStatusTransition, type Session, type SessionRetryState, type SessionStatus, type Agent, type Provider } from "../types/session"
 import { deleteSession, loadMessages } from "./session-api"
 import { showToastNotification } from "../lib/notifications"
 import { messageStoreBus } from "./message-v2/bus"
-import { instances } from "./instances"
+import { instances, ensureYoloStateSynced } from "./instances"
 import { showConfirmDialog } from "./alerts"
 import { getLogger } from "../lib/logger"
 import { requestData } from "../lib/opencode-api"
@@ -13,8 +13,36 @@ import { getOpenCodeWorkspaceIdForSession } from "./opencode-workspaces"
 import { tGlobal } from "../lib/i18n"
 import { computeThreadTotals, type ThreadTotals } from "../lib/thread-totals"
 import { applySessionPage, getDefaultSessionPaginationState, type SessionPaginationState } from "./session-pagination-model"
+import { applySessionPendingState } from "./session-pending-state"
+import {
+  resolveAuthoritativeGenerationRecovery,
+  resolveHydratedGenerationRecovery,
+  type PersistedGenerationRecovery,
+} from "./session-generation-recovery"
+import {
+  buildSessionThreadsFromMap,
+  collectVisibleSessionIds,
+  getDescendantSessionsFromMap,
+  getSessionAncestorIdsFromMap,
+  getSessionRootFromMap,
+  type SessionThread,
+} from "./session-tree"
+
+export type { SessionThread } from "./session-tree"
 
 const log = getLogger("session")
+let generationAdmissionSequence = 0
+interface GenerationAdmission {
+  token: number
+  pending: number
+  accepted: boolean
+  baseline: Pick<Session, "generationRecovery" | "runtimeStatusKnown" | "idleSince">
+}
+const generationAdmissions = new Map<string, GenerationAdmission>()
+
+function cancelSessionGenerationAdmissions(instanceId: string, sessionId: string): void {
+  generationAdmissions.delete(`${instanceId}:${sessionId}`)
+}
 
 export interface SessionInfo {
   cost: number
@@ -28,18 +56,18 @@ export interface SessionInfo {
   contextAvailableTokens: number | null
 }
 
-export type SessionThread = {
-  parent: Session
-  children: Session[]
-  latestUpdated: number
-}
-
 const [sessions, setSessions] = createSignal<Map<string, Map<string, Session>>>(new Map())
 const [activeSessionId, setActiveSessionId] = createSignal<Map<string, string>>(new Map())
 const [activeParentSessionId, setActiveParentSessionId] = createSignal<Map<string, string>>(new Map())
 const [agents, setAgents] = createSignal<Map<string, Agent[]>>(new Map())
 const [providers, setProviders] = createSignal<Map<string, Provider[]>>(new Map())
 const [sessionDraftPrompts, setSessionDraftPrompts] = createSignal<Map<string, string>>(new Map())
+const [authoritativeDraftKeys, setAuthoritativeDraftKeys] = createSignal<Set<string>>(new Set())
+const [authoritativeSessionSelectionInstanceIds, setAuthoritativeSessionSelectionInstanceIds] = createSignal<Set<string>>(new Set())
+const [authoritativelyDeletedSessionKeys, setAuthoritativelyDeletedSessionKeys] = createSignal<Set<string>>(new Set())
+const [authoritativeSessionExpansionKeys, setAuthoritativeSessionExpansionKeys] = createSignal<Set<string>>(new Set())
+type SessionDraftHydratedListener = (instanceId: string, sessionId: string, draft: string) => void
+const sessionDraftHydratedListeners = new Set<SessionDraftHydratedListener>()
 
 const [loading, setLoading] = createSignal({
   fetchingSessions: new Map<string, boolean>(),
@@ -50,10 +78,14 @@ const [loading, setLoading] = createSignal({
 
 const [messagesLoaded, setMessagesLoaded] = createSignal<Map<string, Set<string>>>(new Map())
 const [messageLoadErrors, setMessageLoadErrors] = createSignal<Map<string, Map<string, string>>>(new Map())
+const [sessionListErrors, setSessionListErrors] = createSignal<Map<string, string>>(new Map())
+const messageLoadEpochs = new Map<string, number>()
+let nextMessageLoadEpoch = 0
 const [sessionInfoByInstance, setSessionInfoByInstance] = createSignal<Map<string, Map<string, SessionInfo>>>(new Map())
 const [threadTotalsByInstance, setThreadTotalsByInstance] = createSignal<Map<string, Map<string, ThreadTotals>>>(new Map())
 
-const [expandedSessionParents, setExpandedSessionParents] = createSignal<Map<string, Set<string>>>(new Map())
+// Track expansion state for ANY session that has children (not just top-level parents)
+const [expandedSessions, setExpandedSessions] = createSignal<Map<string, Set<string>>>(new Map())
 
 export type InstanceSessionIndicatorStatus = "permission" | SessionStatus
 
@@ -77,6 +109,13 @@ type SessionSearchState = {
 const [sessionPagination, setSessionPagination] = createSignal<Map<string, SessionPaginationState>>(new Map())
 const [sessionSearch, setSessionSearch] = createSignal<Map<string, SessionSearchState>>(new Map())
 
+function updateSessionPagination(
+  instanceId: string,
+  update: (current: SessionPaginationState | undefined) => SessionPaginationState,
+): void {
+  setSessionPagination((prev) => new Map(prev).set(instanceId, update(prev.get(instanceId))))
+}
+
 function getSessionPaginationState(instanceId: string): SessionPaginationState {
   return sessionPagination().get(instanceId) ?? getDefaultSessionPaginationState()
 }
@@ -90,11 +129,7 @@ function getSessionNextCursor(instanceId: string): string | undefined {
 }
 
 function setSessionPage(instanceId: string, ids: string[], hasMore: boolean, reset = false, nextCursor?: string): void {
-  setSessionPagination((prev) => {
-    const next = new Map(prev)
-    next.set(instanceId, applySessionPage(prev.get(instanceId), ids, hasMore, reset, nextCursor))
-    return next
-  })
+  updateSessionPagination(instanceId, (current) => applySessionPage(current, ids, hasMore, reset, nextCursor))
 }
 
 function getSessionHasMore(instanceId: string): boolean {
@@ -102,30 +137,20 @@ function getSessionHasMore(instanceId: string): boolean {
 }
 
 function resetSessionPagination(instanceId: string): void {
-  setSessionPagination((prev) => {
-    const next = new Map(prev)
-    next.set(instanceId, getDefaultSessionPaginationState())
-    return next
-  })
+  updateSessionPagination(instanceId, getDefaultSessionPaginationState)
 }
 
 function prependSessionListId(instanceId: string, sessionId: string): void {
-  setSessionPagination((prev) => {
-    const next = new Map(prev)
-    const current = prev.get(instanceId) ?? { ids: [], hasMore: true }
-    const ids = [sessionId, ...current.ids.filter((id) => id !== sessionId)]
-    next.set(instanceId, { ...current, ids })
-    return next
+  updateSessionPagination(instanceId, (value) => {
+    const current = value ?? { ids: [], hasMore: true }
+    return { ...current, ids: [sessionId, ...current.ids.filter((id) => id !== sessionId)] }
   })
 }
 
 function removeSessionListId(instanceId: string, sessionId: string): void {
-  setSessionPagination((prev) => {
-    const next = new Map(prev)
-    const current = prev.get(instanceId) ?? { ids: [], hasMore: true }
-    const ids = current.ids.filter((id) => id !== sessionId)
-    next.set(instanceId, { ...current, ids })
-    return next
+  updateSessionPagination(instanceId, (value) => {
+    const current = value ?? { ids: [], hasMore: true }
+    return { ...current, ids: current.ids.filter((id) => id !== sessionId) }
   })
 }
 
@@ -310,12 +335,39 @@ function clearLoadedFlag(instanceId: string, sessionId: string) {
   })
 }
 
-messageStoreBus.onSessionCleared((instanceId, sessionId) => {
+function advanceMessageLoadEpoch(instanceId: string, sessionId: string): number {
+  const key = getDraftKey(instanceId, sessionId)
+  const epoch = ++nextMessageLoadEpoch
+  messageLoadEpochs.set(key, epoch)
+  return epoch
+}
+
+function isCurrentMessageLoad(instanceId: string, sessionId: string, epoch: number): boolean {
+  return messageLoadEpochs.get(getDraftKey(instanceId, sessionId)) === epoch
+}
+
+function clearMessageLoadingFlag(instanceId: string, sessionId: string): void {
+  setLoading((prev) => {
+    const existing = prev.loadingMessages.get(instanceId)
+    if (!existing?.has(sessionId)) return prev
+    const loadingMessages = new Map(prev.loadingMessages)
+    const updated = new Set(existing)
+    updated.delete(sessionId)
+    if (updated.size === 0) loadingMessages.delete(instanceId)
+    else loadingMessages.set(instanceId, updated)
+    return { ...prev, loadingMessages }
+  })
+}
+
+function invalidateSessionMessageLoad(instanceId: string, sessionId: string): void {
+  advanceMessageLoadEpoch(instanceId, sessionId)
   clearLoadedFlag(instanceId, sessionId)
-})
+  clearMessageLoadingFlag(instanceId, sessionId)
+}
+
+messageStoreBus.onSessionCleared(invalidateSessionMessageLoad)
 
 function getDraftKey(instanceId: string, sessionId: string): string {
-
   return `${instanceId}:${sessionId}`
 }
 
@@ -325,7 +377,7 @@ function getSessionDraftPrompt(instanceId: string, sessionId: string): string {
   return sessionDraftPrompts().get(key) ?? ""
 }
 
-function setSessionDraftPrompt(instanceId: string, sessionId: string, value: string) {
+function writeSessionDraftPrompt(instanceId: string, sessionId: string, value: string) {
   const key = getDraftKey(instanceId, sessionId)
   setSessionDraftPrompts((prev) => {
     const next = new Map(prev)
@@ -338,8 +390,86 @@ function setSessionDraftPrompt(instanceId: string, sessionId: string, value: str
   })
 }
 
+function addAuthoritativeKey(setter: typeof setAuthoritativeDraftKeys, key: string): void {
+  setter((prev) => {
+    if (prev.has(key)) return prev
+    const next = new Set(prev)
+    next.add(key)
+    return next
+  })
+}
+
+function markSessionDraftAuthoritative(instanceId: string, sessionId: string) {
+  addAuthoritativeKey(setAuthoritativeDraftKeys, getDraftKey(instanceId, sessionId))
+}
+
+function setSessionDraftPrompt(instanceId: string, sessionId: string, value: string) {
+  markSessionDraftAuthoritative(instanceId, sessionId)
+  writeSessionDraftPrompt(instanceId, sessionId, value)
+}
+
+function hydrateSessionDraftPrompt(instanceId: string, sessionId: string, value: string): void {
+  writeSessionDraftPrompt(instanceId, sessionId, value)
+  for (const listener of sessionDraftHydratedListeners) listener(instanceId, sessionId, value)
+}
+
+function onSessionDraftHydrated(listener: SessionDraftHydratedListener): () => void {
+  sessionDraftHydratedListeners.add(listener)
+  return () => sessionDraftHydratedListeners.delete(listener)
+}
+
+function getSessionDraftPromptsForInstance(instanceId: string): Record<string, string> {
+  if (!instanceId) return {}
+  const prefix = `${instanceId}:`
+  const result: Record<string, string> = {}
+  for (const [key, value] of sessionDraftPrompts()) {
+    if (!key.startsWith(prefix) || !value) continue
+    result[key.slice(prefix.length)] = value
+  }
+  return result
+}
+
+function getAuthoritativeSessionIds(keys: ReadonlySet<string>, instanceId: string): ReadonlySet<string> {
+  if (!instanceId) return new Set()
+  const prefix = `${instanceId}:`
+  return new Set(
+    [...keys]
+      .filter((key) => key.startsWith(prefix))
+      .map((key) => key.slice(prefix.length)),
+  )
+}
+
+function getAuthoritativeDraftSessionIdsForInstance(instanceId: string): ReadonlySet<string> {
+  return getAuthoritativeSessionIds(authoritativeDraftKeys(), instanceId)
+}
+
+function getAuthoritativelyDeletedSessionIdsForInstance(instanceId: string): ReadonlySet<string> {
+  return getAuthoritativeSessionIds(authoritativelyDeletedSessionKeys(), instanceId)
+}
+
+function getAuthoritativeSessionExpansionIdsForInstance(instanceId: string): ReadonlySet<string> {
+  return getAuthoritativeSessionIds(authoritativeSessionExpansionKeys(), instanceId)
+}
+
+function markSessionDeletedAuthoritative(instanceId: string, sessionId: string): void {
+  addAuthoritativeKey(setAuthoritativelyDeletedSessionKeys, getDraftKey(instanceId, sessionId))
+}
+
+function clearInstanceDeletedSessionAuthority(instanceId: string): void {
+  if (!instanceId) return
+  const prefix = `${instanceId}:`
+  for (const key of messageLoadEpochs.keys()) {
+    if (key.startsWith(prefix)) messageLoadEpochs.delete(key)
+  }
+  setAuthoritativelyDeletedSessionKeys((prev) => {
+    const next = new Set([...prev].filter((key) => !key.startsWith(prefix)))
+    return next.size === prev.size ? prev : next
+  })
+}
+
 function clearSessionDraftPrompt(instanceId: string, sessionId: string) {
   const key = getDraftKey(instanceId, sessionId)
+  markSessionDraftAuthoritative(instanceId, sessionId)
   setSessionDraftPrompts((prev) => {
     if (!prev.has(key)) return prev
     const next = new Map(prev)
@@ -348,7 +478,7 @@ function clearSessionDraftPrompt(instanceId: string, sessionId: string) {
   })
 }
 
-function clearInstanceDraftPrompts(instanceId: string) {
+function clearInstanceDraftPromptValues(instanceId: string) {
   if (!instanceId) return
   setSessionDraftPrompts((prev) => {
     let changed = false
@@ -364,6 +494,20 @@ function clearInstanceDraftPrompts(instanceId: string) {
   })
 }
 
+function clearInstanceDraftPromptAuthority(instanceId: string) {
+  if (!instanceId) return
+  setAuthoritativeDraftKeys((prev) => {
+    const prefix = `${instanceId}:`
+    const next = new Set([...prev].filter((key) => !key.startsWith(prefix)))
+    return next.size === prev.size ? prev : next
+  })
+}
+
+function clearInstanceDraftPrompts(instanceId: string) {
+  clearInstanceDraftPromptValues(instanceId)
+  clearInstanceDraftPromptAuthority(instanceId)
+}
+
 function pruneDraftPrompts(instanceId: string, validSessionIds: Set<string>) {
   setSessionDraftPrompts((prev) => {
     let changed = false
@@ -417,18 +561,48 @@ function withSession(instanceId: string, sessionId: string, updater: (session: S
   }
 }
 
-function setSessionPendingPermission(instanceId: string, sessionId: string, pending: boolean): void {
+function setSessionPending(
+  instanceId: string,
+  sessionId: string,
+  field: "pendingPermission" | "pendingQuestion",
+  pending: boolean,
+): void {
+  if (pending) cancelSessionGenerationAdmissions(instanceId, sessionId)
   withSession(instanceId, sessionId, (session) => {
-    if (session.pendingPermission === pending) return false
-    session.pendingPermission = pending
+    if (session[field] === pending && (!pending || !session.generationRecovery)) return false
+    session[field] = pending
+    if (pending) {
+      session.generationRecovery = null
+      session.generationAdmissionToken = undefined
+    }
   })
 }
 
+function setSessionPendingPermission(instanceId: string, sessionId: string, pending: boolean): void {
+  setSessionPending(instanceId, sessionId, "pendingPermission", pending)
+}
+
 function setSessionPendingQuestion(instanceId: string, sessionId: string, pending: boolean): void {
-  withSession(instanceId, sessionId, (session) => {
-    if (session.pendingQuestion === pending) return false
-    session.pendingQuestion = pending
+  setSessionPending(instanceId, sessionId, "pendingQuestion", pending)
+}
+
+function reconcileSessionPendingState(
+  instanceId: string,
+  permissionSessionIds: ReadonlySet<string>,
+  questionSessionIds: ReadonlySet<string>,
+): void {
+  setSessions((prev) => {
+    const instanceSessions = prev.get(instanceId)
+    if (!instanceSessions) return prev
+
+    const reconciled = applySessionPendingState(instanceSessions, permissionSessionIds, questionSessionIds)
+    if (reconciled === instanceSessions) return prev
+
+    const next = new Map(prev)
+    next.set(instanceId, reconciled)
+    return next
   })
+  syncInstanceSessionIndicator(instanceId)
 }
 
 function markSessionIdleSeen(instanceId: string, sessionId: string): void {
@@ -444,93 +618,208 @@ function markViewedSessionIdleSeen(
   sessionId: string,
   keepUnseenSubagentIdleStatus: boolean,
 ): void {
-  setSessions((prev) => {
-    const instanceSessions = prev.get(instanceId)
-    if (!instanceSessions) return prev
+  const instanceSessions = sessions().get(instanceId)
+  const viewedSession = instanceSessions?.get(sessionId)
+  if (!instanceSessions || !viewedSession) return
+  const ids = viewedSession.parentId === null && !keepUnseenSubagentIdleStatus
+    ? [sessionId, ...getDescendantSessionsFromMap(instanceSessions, sessionId).map((session) => session.id)]
+    : [sessionId]
+  batch(() => ids.forEach((id) => markSessionIdleSeen(instanceId, id)))
+}
 
-    const viewedSession = instanceSessions.get(sessionId)
-    if (!viewedSession) return prev
-
-    const idsToClear = new Set<string>([sessionId])
-    if (viewedSession.parentId === null && !keepUnseenSubagentIdleStatus) {
-      for (const session of instanceSessions.values()) {
-        if (session.parentId === sessionId) idsToClear.add(session.id)
-      }
-    }
-
-    let changed = false
-    const updatedSessions = new Map(instanceSessions)
-    for (const id of idsToClear) {
-      const session = updatedSessions.get(id)
-      if (!session) continue
-      if (session.status !== "idle") continue
-      if (typeof session.idleSince !== "number") continue
-      updatedSessions.set(id, { ...session, idleSince: null })
-      changed = true
-    }
-
-    if (!changed) return prev
-
-    const next = new Map(prev)
-    next.set(instanceId, updatedSessions)
+function markSessionSelectionAuthoritative(instanceId: string): void {
+  setAuthoritativeSessionSelectionInstanceIds((prev) => {
+    if (prev.has(instanceId)) return prev
+    const next = new Set(prev)
+    next.add(instanceId)
     return next
   })
 }
 
+function hydrateSessionIdleMarkers(instanceId: string, markers: Readonly<Record<string, number>>): void {
+  for (const [sessionId, idleSince] of Object.entries(markers)) {
+    withSession(instanceId, sessionId, (session) => {
+      if (session.status !== "idle" || typeof session.idleSince === "number") return false
+      session.idleSince = idleSince
+    })
+  }
+}
+
+function hydrateSessionGenerationRecovery(
+  instanceId: string,
+  markers: Readonly<Record<string, PersistedGenerationRecovery>>,
+): void {
+  for (const [sessionId, persisted] of Object.entries(markers)) {
+    withSession(instanceId, sessionId, (session) => {
+      const recovery = session.pendingPermission || session.pendingQuestion
+        ? null
+        : resolveHydratedGenerationRecovery(persisted, session.status, session.runtimeStatusKnown === true)
+      if ((session.generationRecovery ?? null) === recovery) return false
+      session.generationRecovery = recovery
+    })
+  }
+}
+
+function beginSessionGenerationAdmission(instanceId: string, sessionId: string): {
+  complete: () => void
+  rollback: () => void
+} {
+  const key = `${instanceId}:${sessionId}`
+  let admission = generationAdmissions.get(key)
+  if (!admission) {
+    const session = sessions().get(instanceId)?.get(sessionId)
+    if (!session) return { complete: () => {}, rollback: () => {} }
+    admission = {
+      token: ++generationAdmissionSequence,
+      pending: 0,
+      accepted: false,
+      baseline: {
+        generationRecovery: session.generationRecovery,
+        runtimeStatusKnown: session.runtimeStatusKnown,
+        idleSince: session.idleSince,
+      },
+    }
+    generationAdmissions.set(key, admission)
+  }
+  admission.pending += 1
+  withSession(instanceId, sessionId, (session) => {
+    session.generationRecovery = "pending"
+    session.runtimeStatusKnown = false
+    session.idleSince = null
+    session.generationAdmissionToken = admission!.token
+  })
+
+  let settled = false
+  const settle = (accepted: boolean) => {
+    if (settled || generationAdmissions.get(key) !== admission) return
+    settled = true
+    admission.accepted ||= accepted
+    if (--admission.pending > 0) return
+    generationAdmissions.delete(key)
+    withSession(instanceId, sessionId, (session) => {
+      if (session.generationAdmissionToken !== admission.token) return false
+      session.generationAdmissionToken = undefined
+      if (admission.accepted) return
+      Object.assign(session, admission.baseline)
+    })
+  }
+  return { complete: () => settle(true), rollback: () => settle(false) }
+}
+
+function hasAuthoritativeSessionSelection(instanceId: string): boolean {
+  return authoritativeSessionSelectionInstanceIds().has(instanceId)
+}
+
+function writeSessionSelection(
+  setter: typeof setActiveSessionId,
+  instanceId: string,
+  sessionId: string | null,
+): void {
+  setter((prev) => {
+    const next = new Map(prev)
+    if (sessionId) next.set(instanceId, sessionId)
+    else next.delete(instanceId)
+    return next
+  })
+}
+
+function writeActiveSession(instanceId: string, sessionId: string | null): void {
+  writeSessionSelection(setActiveSessionId, instanceId, sessionId)
+  if (sessionId) {
+    // Backfill authoritative Yolo state for the now-active session so the badge
+    // matches the server even on first connect / multi-client scenarios.
+    ensureYoloStateSynced(instanceId, sessionId)
+  }
+}
+
+function writeActiveParentSession(instanceId: string, parentSessionId: string | null): void {
+  writeSessionSelection(setActiveParentSessionId, instanceId, parentSessionId)
+}
+
 function setActiveSession(instanceId: string, sessionId: string): void {
-  setActiveSessionId((prev) => {
-    const next = new Map(prev)
-    next.set(instanceId, sessionId)
-    return next
-  })
+  markSessionSelectionAuthoritative(instanceId)
+  writeActiveSession(instanceId, sessionId)
 }
 
 function setActiveParentSession(instanceId: string, parentSessionId: string): void {
-  setActiveParentSessionId((prev) => {
-    const next = new Map(prev)
-    next.set(instanceId, parentSessionId)
-    return next
-  })
-
-  setActiveSession(instanceId, parentSessionId)
+  markSessionSelectionAuthoritative(instanceId)
+  writeActiveParentSession(instanceId, parentSessionId)
+  writeActiveSession(instanceId, parentSessionId)
 }
 
 function clearActiveParentSession(instanceId: string): void {
-  setActiveParentSessionId((prev) => {
-    const next = new Map(prev)
-    next.delete(instanceId)
-    return next
-  })
+  markSessionSelectionAuthoritative(instanceId)
+  writeActiveParentSession(instanceId, null)
+  writeActiveSession(instanceId, null)
+}
 
-  setActiveSessionId((prev) => {
-    const next = new Map(prev)
+function clearActiveSession(instanceId: string): void {
+  markSessionSelectionAuthoritative(instanceId)
+  writeActiveSession(instanceId, null)
+}
+
+function hydrateActiveSessionSelection(
+  instanceId: string,
+  parentSessionId: string | null,
+  sessionId: string | null,
+): void {
+  if (hasAuthoritativeSessionSelection(instanceId)) return
+  writeActiveParentSession(instanceId, parentSessionId)
+  writeActiveSession(instanceId, sessionId)
+}
+
+function clearInstanceSessionSelection(instanceId: string): void {
+  writeActiveParentSession(instanceId, null)
+  writeActiveSession(instanceId, null)
+  setAuthoritativeSessionSelectionInstanceIds((prev) => {
+    if (!prev.has(instanceId)) return prev
+    const next = new Set(prev)
     next.delete(instanceId)
     return next
   })
 }
 
-function setSessionStatus(instanceId: string, sessionId: string, status: SessionStatus): void {
-  let parentToExpand: string | null = null
+function setSessionStatus(
+  instanceId: string,
+  sessionId: string,
+  status: SessionStatus,
+  options: { retry?: SessionRetryState | null; force?: boolean } = {},
+): void {
+  let expandAncestors = false
 
   withSession(instanceId, sessionId, (session) => {
-    if (session.status === status) return false
+    const admissionPending = session.generationAdmissionToken !== undefined && status === "idle"
+    const generationRecovery = admissionPending
+      ? "pending"
+      : resolveAuthoritativeGenerationRecovery(session.generationRecovery, status)
+    const retry = status === "working" ? options.retry ?? null : null
+    const sameRetry = session.retry?.attempt === retry?.attempt
+      && session.retry?.message === retry?.message
+      && session.retry?.next === retry?.next
+    if (
+      session.status === status
+      && sameRetry
+      && session.runtimeStatusKnown === !admissionPending
+      && (session.generationRecovery ?? null) === generationRecovery
+    ) return false
+    if (session.status === "compacting" && status !== "compacting" && !options.force) return false
     const previous = session.status
     session.status = status
-    session.idleSince = getIdleSinceForStatusTransition(previous, status, session.idleSince)
-    if (status !== "working") {
-      session.retry = null
+    session.runtimeStatusKnown = !admissionPending
+    session.generationRecovery = generationRecovery
+    if (!admissionPending) {
+      cancelSessionGenerationAdmissions(instanceId, sessionId)
+      session.generationAdmissionToken = undefined
     }
+    session.idleSince = getIdleSinceForStatusTransition(previous, status, session.idleSince)
+    session.retry = retry
 
-    // If a child session starts working, auto-expand its parent thread once.
-    // Users can still collapse it afterwards; we only expand on the transition.
     if (session.parentId && status === "working" && previous !== "working") {
-      parentToExpand = session.parentId
+      expandAncestors = true
     }
   })
 
-  if (parentToExpand) {
-    ensureSessionParentExpanded(instanceId, parentToExpand)
-  }
+  if (expandAncestors) ensureSessionAncestorsExpanded(instanceId, sessionId)
 }
 
 function getActiveParentSession(instanceId: string): Session | null {
@@ -565,33 +854,8 @@ function getChildSessions(instanceId: string, parentId: string): Session[] {
 }
 
 function getDescendantSessions(instanceId: string, parentId: string): Session[] {
-  const allSessions = getSessions(instanceId)
-  const childrenByParent = new Map<string, Session[]>()
-
-  for (const session of allSessions) {
-    if (!session.parentId) continue
-    const children = childrenByParent.get(session.parentId)
-    if (children) {
-      children.push(session)
-    } else {
-      childrenByParent.set(session.parentId, [session])
-    }
-  }
-
-  const descendants: Session[] = []
-  const stack = [...(childrenByParent.get(parentId) ?? [])]
-  const seen = new Set<string>()
-
-  while (stack.length > 0) {
-    const session = stack.shift()
-    if (!session || seen.has(session.id)) continue
-    seen.add(session.id)
-    descendants.push(session)
-    stack.push(...(childrenByParent.get(session.id) ?? []))
-  }
-
-  descendants.sort((a, b) => (b.time.updated ?? 0) - (a.time.updated ?? 0))
-  return descendants
+  const instanceSessions = sessions().get(instanceId)
+  return instanceSessions ? getDescendantSessionsFromMap(instanceSessions, parentId) : []
 }
 
 function getSessionFamily(instanceId: string, parentId: string): Session[] {
@@ -608,112 +872,9 @@ function getSessionRoot(instanceId: string, sessionId: string): Session | null {
   return getSessionRootFromMap(instanceSessions, sessionId)
 }
 
-function getSessionRootFromMap(instanceSessions: Map<string, Session>, sessionId: string): Session | null {
-  let current = instanceSessions.get(sessionId)
-  if (!current) return null
-
-  const seen = new Set<string>()
-  while (current.parentId) {
-    if (seen.has(current.id)) return null
-    seen.add(current.id)
-    const parent = instanceSessions.get(current.parentId)
-    if (!parent) return null
-    current = parent
-  }
-
-  return current
-}
-
-type SessionThreadCacheEntry = {
-  signature: string
-  thread: SessionThread
-}
-
-type SessionThreadCache = {
-  byParentId: Map<string, SessionThreadCacheEntry>
-}
-
-const sessionThreadCache = new Map<string, SessionThreadCache>()
-
-function getOrCreateSessionThreadCache(instanceId: string): SessionThreadCache {
-  let cache = sessionThreadCache.get(instanceId)
-  if (!cache) {
-    cache = { byParentId: new Map() }
-    sessionThreadCache.set(instanceId, cache)
-  }
-  return cache
-}
-
 function buildSessionThreads(instanceId: string, rootIds: string[], childIds?: Set<string>): SessionThread[] {
   const instanceSessions = sessions().get(instanceId)
-  if (!instanceSessions || instanceSessions.size === 0 || rootIds.length === 0) {
-    sessionThreadCache.delete(instanceId)
-    return []
-  }
-
-  const cache = getOrCreateSessionThreadCache(instanceId)
-  const seenParents = new Set<string>()
-
-  const childrenByRoot = new Map<string, Session[]>()
-
-  for (const session of instanceSessions.values()) {
-    if (!session.parentId) continue
-    if (childIds && !childIds.has(session.id)) continue
-    const root = getSessionRootFromMap(instanceSessions, session.id)
-    if (!root) continue
-    const children = childrenByRoot.get(root.id)
-    if (children) {
-      children.push(session)
-    } else {
-      childrenByRoot.set(root.id, [session])
-    }
-  }
-
-  const threads: SessionThread[] = []
-
-  for (const parentId of rootIds) {
-    const parent = instanceSessions.get(parentId)
-    if (!parent || parent.parentId !== null) continue
-
-    seenParents.add(parent.id)
-
-    const children = childrenByRoot.get(parent.id) ?? []
-    if (children.length > 1) {
-      children.sort((a, b) => (b.time.updated ?? 0) - (a.time.updated ?? 0))
-    }
-
-    const parentUpdated = parent.time.updated ?? 0
-    const latestChild = children[0]?.time.updated ?? 0
-    const latestUpdated = Math.max(parentUpdated, latestChild)
-
-    const childIds = children.map((child) => child.id).join(",")
-    const signature = `${parentUpdated}:${latestChild}:${childIds}`
-
-    const cached = cache.byParentId.get(parent.id)
-    if (cached && cached.signature === signature) {
-      threads.push(cached.thread)
-    } else {
-      const thread: SessionThread = { parent, children, latestUpdated }
-      cache.byParentId.set(parent.id, { signature, thread })
-      threads.push(thread)
-    }
-  }
-
-  for (const parentId of Array.from(cache.byParentId.keys())) {
-    if (!seenParents.has(parentId)) {
-      cache.byParentId.delete(parentId)
-    }
-  }
-
-  threads.sort((a, b) => {
-    if (b.latestUpdated !== a.latestUpdated) return b.latestUpdated - a.latestUpdated
-    const bParentUpdated = b.parent.time.updated ?? 0
-    const aParentUpdated = a.parent.time.updated ?? 0
-    if (bParentUpdated !== aParentUpdated) return bParentUpdated - aParentUpdated
-    return b.parent.id.localeCompare(a.parent.id)
-  })
-
-  return threads
+  return instanceSessions ? buildSessionThreadsFromMap(instanceSessions, rootIds, childIds) : []
 }
 
 function getSessionThreads(instanceId: string): SessionThread[] {
@@ -734,7 +895,7 @@ function getSessionSearchThreads(instanceId: string): SessionThread[] {
     const session = instanceSessions.get(sessionId)
     if (!session) continue
     if (session.parentId === null) {
-      rootIds.push(session.id)
+      if (!rootIds.includes(session.id)) rootIds.push(session.id)
     } else {
       childIds.add(session.id)
       const root = getSessionRootFromMap(instanceSessions, session.id)
@@ -745,20 +906,19 @@ function getSessionSearchThreads(instanceId: string): SessionThread[] {
   return buildSessionThreads(instanceId, rootIds, childIds)
 }
 
-function isSessionParentExpanded(instanceId: string, parentSessionId: string): boolean {
-  return Boolean(expandedSessionParents().get(instanceId)?.has(parentSessionId))
+function isSessionExpanded(instanceId: string, sessionId: string): boolean {
+  return Boolean(expandedSessions().get(instanceId)?.has(sessionId))
 }
 
-function setSessionParentExpanded(instanceId: string, parentSessionId: string, expanded: boolean): void {
-  setExpandedSessionParents((prev) => {
+function setSessionExpanded(instanceId: string, sessionId: string, expanded: boolean): void {
+  addAuthoritativeKey(setAuthoritativeSessionExpansionKeys, getDraftKey(instanceId, sessionId))
+  setExpandedSessions((prev) => {
     const next = new Map(prev)
     const currentSet = next.get(instanceId) ?? new Set<string>()
-    const updated = new Set(currentSet)
+    const updated = expanded ? new Set([sessionId, ...currentSet]) : new Set(currentSet)
 
-    if (expanded) {
-      updated.add(parentSessionId)
-    } else {
-      updated.delete(parentSessionId)
+    if (!expanded) {
+      updated.delete(sessionId)
     }
 
     if (updated.size === 0) {
@@ -771,62 +931,90 @@ function setSessionParentExpanded(instanceId: string, parentSessionId: string, e
   })
 }
 
-function toggleSessionParentExpanded(instanceId: string, parentSessionId: string): void {
-  setExpandedSessionParents((prev) => {
+function clearInstanceSessionExpansionState(instanceId: string): void {
+  if (!instanceId) return
+  const prefix = `${instanceId}:`
+  setExpandedSessions((prev) => {
+    if (!prev.has(instanceId)) return prev
     const next = new Map(prev)
-    const currentSet = next.get(instanceId) ?? new Set<string>()
-    const updated = new Set(currentSet)
+    next.delete(instanceId)
+    return next
+  })
+  setAuthoritativeSessionExpansionKeys((prev) => {
+    const next = new Set([...prev].filter((key) => !key.startsWith(prefix)))
+    return next.size === prev.size ? prev : next
+  })
+}
 
-    if (updated.has(parentSessionId)) {
-      updated.delete(parentSessionId)
-    } else {
-      updated.add(parentSessionId)
-    }
-
-    next.set(instanceId, updated)
+function hydrateSessionExpansion(instanceId: string, sessionIds: readonly string[]): void {
+  setExpandedSessions((prev) => {
+    const current = prev.get(instanceId)
+    const authoritative = getAuthoritativeSessionExpansionIdsForInstance(instanceId)
+    const deleted = getAuthoritativelyDeletedSessionIdsForInstance(instanceId)
+    const expanded = new Set(sessionIds.filter((id) => !authoritative.has(id) && !deleted.has(id)))
+    for (const id of current ?? []) if (authoritative.has(id) && !deleted.has(id)) expanded.add(id)
+    if (current?.size === expanded.size && [...expanded].every((id) => current.has(id))) return prev
+    const next = new Map(prev)
+    if (expanded.size) next.set(instanceId, expanded)
+    else next.delete(instanceId)
+    return next
+  })
+  setAuthoritativeSessionExpansionKeys((prev) => {
+    const next = new Set(prev)
+    for (const id of sessions().get(instanceId)?.keys() ?? []) next.add(getDraftKey(instanceId, id))
     return next
   })
 }
 
-function ensureSessionParentExpanded(instanceId: string, parentSessionId: string): void {
-  if (isSessionParentExpanded(instanceId, parentSessionId)) return
-  setSessionParentExpanded(instanceId, parentSessionId, true)
+function toggleSessionExpanded(instanceId: string, sessionId: string): void {
+  setSessionExpanded(instanceId, sessionId, !isSessionExpanded(instanceId, sessionId))
+}
+
+function ensureSessionExpanded(instanceId: string, sessionId: string): void {
+  if (isSessionExpanded(instanceId, sessionId)) return
+  setSessionExpanded(instanceId, sessionId, true)
+}
+
+function getSessionAncestorIds(instanceId: string, sessionId: string): string[] {
+  const instanceSessions = sessions().get(instanceId)
+  return instanceSessions ? getSessionAncestorIdsFromMap(instanceSessions, sessionId) : []
+}
+
+function ensureSessionAncestorsExpanded(instanceId: string, sessionId: string): void {
+  const ancestorIds = getSessionAncestorIds(instanceId, sessionId)
+  if (ancestorIds.length === 0) return
+  for (const ancestorId of ancestorIds) {
+    addAuthoritativeKey(setAuthoritativeSessionExpansionKeys, getDraftKey(instanceId, ancestorId))
+  }
+  setExpandedSessions((prev) => {
+    const next = new Map(prev)
+    const current = next.get(instanceId) ?? new Set<string>()
+    const missing = ancestorIds.filter((ancestorId) => !current.has(ancestorId))
+    if (missing.length === 0) return prev
+    const expanded = new Set([...missing, ...current])
+    next.set(instanceId, expanded)
+    return next
+  })
 }
 
 function getVisibleSessionIds(instanceId: string): string[] {
   const threads = getSessionThreads(instanceId)
   if (threads.length === 0) return []
 
-  const expanded = expandedSessionParents().get(instanceId)
-  const ids: string[] = []
-
-  for (const thread of threads) {
-    ids.push(thread.parent.id)
-    if (expanded?.has(thread.parent.id)) {
-      for (const child of thread.children) {
-        ids.push(child.id)
-      }
-    }
-  }
-
-  return ids
+  const expanded = expandedSessions().get(instanceId)
+  return collectVisibleSessionIds(threads, expanded)
 }
 
 function setActiveSessionFromList(instanceId: string, sessionId: string): void {
   const session = sessions().get(instanceId)?.get(sessionId)
   if (!session) return
-
-  if (session.parentId === null) {
-    setActiveParentSession(instanceId, sessionId)
-    return
-  }
-
-  const parentId = session.parentId
-  if (!parentId) return
+  const root = getSessionRoot(instanceId, sessionId)
+  if (!root) return
+  ensureSessionAncestorsExpanded(instanceId, sessionId)
 
   batch(() => {
-    setActiveParentSession(instanceId, parentId)
-    setActiveSession(instanceId, sessionId)
+    setActiveParentSession(instanceId, root.id)
+    if (session.id !== root.id) setActiveSession(instanceId, session.id)
   })
 }
 
@@ -845,6 +1033,22 @@ function getSessionMessagesLoadError(instanceId: string, sessionId: string): str
   return messageLoadErrors().get(instanceId)?.get(sessionId)
 }
 
+function getSessionListError(instanceId: string): string | undefined {
+  return sessionListErrors().get(instanceId)
+}
+
+function setSessionListError(instanceId: string, error: string | null): void {
+  setSessionListErrors((prev) => {
+    const next = new Map(prev)
+    if (error) {
+      next.set(instanceId, error)
+    } else {
+      next.delete(instanceId)
+    }
+    return next
+  })
+}
+
 function setSessionMessagesLoadError(instanceId: string, sessionId: string, error: string | null): void {
   setMessageLoadErrors((prev) => {
     const next = new Map(prev)
@@ -888,9 +1092,10 @@ function updateThreadTotalsForParent(instanceId: string, parentSessionId: string
 }
 
 function updateThreadTotalsForSession(instanceId: string, sessionId: string): void {
-  const session = sessions().get(instanceId)?.get(sessionId)
-  if (!session) return
-  updateThreadTotalsForParent(instanceId, session.parentId ?? session.id)
+  const instanceSessions = sessions().get(instanceId)
+  if (!instanceSessions?.has(sessionId)) return
+  const familyIds = [...getSessionAncestorIdsFromMap(instanceSessions, sessionId), sessionId]
+  for (const familyId of familyIds) updateThreadTotalsForParent(instanceId, familyId)
 }
 
 async function isBlankSession(session: Session, instanceId: string, fetchIfNeeded = false): Promise<boolean> {
@@ -905,20 +1110,20 @@ async function isBlankSession(session: Session, instanceId: string, fetchIfNeede
   }
 
   // For a more thorough deep clean, we need to look at actual messages
-  
+
   const instance = instances().get(instanceId)
   if (!instance?.client) {
     return isFreshSession
   }
   let messages: any[] = []
-    try {
-      const client = getRootClient(instanceId)
-      const workspace = await getOpenCodeWorkspaceIdForSession(instanceId, session.id)
-      messages = await requestData<any[]>(
-        client.session.messages({ sessionID: session.id, ...(workspace ? { workspace } : {}) }),
-        "session.messages",
-      )
-    } catch (error) {
+  try {
+    const client = getRootClient(instanceId)
+    const workspace = await getOpenCodeWorkspaceIdForSession(instanceId, session.id)
+    messages = await requestData<any[]>(
+      client.session.messages({ sessionID: session.id, ...(workspace ? { workspace } : {}) }),
+      "session.messages",
+    )
+  } catch (error) {
     log.error(`Failed to fetch messages for session ${session.id}`, error)
     return isFreshSession
   }
@@ -932,23 +1137,23 @@ async function isBlankSession(session: Session, instanceId: string, fetchIfNeede
     // Subagent: "blank" (really: finished doing its job) if actually blank...
     // ... OR no streaming, no pending perms, no tool parts
     if (messages.length === 0) return true
-    
+
     const hasStreaming = messages.some((msg) => {
       const info = msg.info.status || msg.status
       return info === "streaming" || info === "sending"
     })
-    
+
     const lastMessage = messages[messages.length - 1]
     const lastParts = lastMessage?.parts || []
-    const hasToolPart = lastParts.some((part: any) => 
+    const hasToolPart = lastParts.some((part: any) =>
       part.type === "tool" || part.data?.type === "tool"
     )
-    
+
     return !hasStreaming && !session.pendingPermission && !hasToolPart
   } else {
     // Fork: blank if somehow has no messages or at revert point
     if (messages.length === 0) return true
-  
+
     const lastMessage = messages[messages.length - 1]
     const lastInfo = lastMessage?.info || lastMessage
     return lastInfo?.id === session.revert?.messageID
@@ -1006,9 +1211,7 @@ export {
   sessions,
   setSessions,
   activeSessionId,
-  setActiveSessionId,
   activeParentSessionId,
-  setActiveParentSessionId,
   agents,
   setAgents,
   providers,
@@ -1017,6 +1220,11 @@ export {
   setLoading,
   messagesLoaded,
   setMessagesLoaded,
+  getSessionListError,
+  setSessionListError,
+  advanceMessageLoadEpoch,
+  isCurrentMessageLoad,
+  invalidateSessionMessageLoad,
   setSessionMessagesLoadError,
   sessionInfoByInstance,
   setSessionInfoByInstance,
@@ -1025,21 +1233,38 @@ export {
   updateThreadTotalsForParent,
   updateThreadTotalsForSession,
   getSessionDraftPrompt,
+  getSessionDraftPromptsForInstance,
+  getAuthoritativeDraftSessionIdsForInstance,
+  getAuthoritativelyDeletedSessionIdsForInstance,
+  getAuthoritativeSessionExpansionIdsForInstance,
+  markSessionDeletedAuthoritative,
+  clearInstanceDeletedSessionAuthority,
+  clearInstanceSessionExpansionState,
+  hydrateSessionDraftPrompt,
+  onSessionDraftHydrated,
   setSessionDraftPrompt,
   clearSessionDraftPrompt,
+  clearInstanceDraftPromptValues,
   clearInstanceDraftPrompts,
   pruneDraftPrompts,
   withSession,
   setSessionPendingPermission,
   setSessionPendingQuestion,
+  reconcileSessionPendingState,
   markSessionIdleSeen,
   markViewedSessionIdleSeen,
+  hydrateSessionIdleMarkers,
+  hydrateSessionGenerationRecovery,
+  beginSessionGenerationAdmission,
+  cancelSessionGenerationAdmissions,
   setSessionStatus,
   setActiveSession,
- 
   setActiveParentSession,
-
+  clearActiveSession,
   clearActiveParentSession,
+  hydrateActiveSessionSelection,
+  hasAuthoritativeSessionSelection,
+  clearInstanceSessionSelection,
   getActiveSession,
   getActiveParentSession,
   getSessions,
@@ -1051,10 +1276,14 @@ export {
   getSessionThreads,
   getSessionSearchThreads,
   getVisibleSessionIds,
-  isSessionParentExpanded,
-  setSessionParentExpanded,
-  toggleSessionParentExpanded,
-  ensureSessionParentExpanded,
+  expandedSessions,
+  isSessionExpanded,
+  setSessionExpanded,
+  hydrateSessionExpansion,
+  toggleSessionExpanded,
+  ensureSessionExpanded,
+  getSessionAncestorIds,
+  ensureSessionAncestorsExpanded,
   setActiveSessionFromList,
   isSessionBusy,
   isSessionMessagesLoading,
diff --git a/packages/ui/src/stores/session-status.test.ts b/packages/ui/src/stores/session-status.test.ts
index aee67714..6cc79ddc 100644
--- a/packages/ui/src/stores/session-status.test.ts
+++ b/packages/ui/src/stores/session-status.test.ts
@@ -90,6 +90,20 @@ describe("idle status visibility", () => {
     markSessionIdleFadeStarted(instanceId, sessionId)
     assert.equal(getSessionIdleFadeClass(instanceId, sessionId), "session-status-fading")
 
+    setSessions(
+      new Map([
+        [instanceId, new Map([[sessionId, { id: sessionId, status: "idle", idleSince: null, parentId: null } as any]])],
+      ]),
+    )
+    assert.equal(getSessionIdleFadeClass(instanceId, sessionId), "session-status-fading")
+
+    setSessions(
+      new Map([
+        [instanceId, new Map([[sessionId, { id: sessionId, status: "idle", idleSince: 2_000, parentId: null } as any]])],
+      ]),
+    )
+    assert.equal(getSessionIdleFadeClass(instanceId, sessionId), "")
+
     clearSessionIdleFade(instanceId, sessionId, idleSince)
     assert.equal(getSessionIdleFadeClass(instanceId, sessionId), "")
 
diff --git a/packages/ui/src/stores/session-status.ts b/packages/ui/src/stores/session-status.ts
index 1566077f..6aeea4f2 100644
--- a/packages/ui/src/stores/session-status.ts
+++ b/packages/ui/src/stores/session-status.ts
@@ -5,10 +5,10 @@ import { createSignal } from "solid-js"
 
 export const IDLE_STATUS_VISIBILITY_MS = 5000
 
-const [idleFadeStarts, setIdleFadeStarts] = createSignal<Map<string, number>>(new Map())
+const [idleFades, setIdleFades] = createSignal<Map<string, number>>(new Map())
 
-function idleFadeKey(instanceId: string, sessionId: string, idleSince: number): string {
-  return `${instanceId}:${sessionId}:${idleSince}`
+function idleFadeKey(instanceId: string, sessionId: string): string {
+  return `${instanceId}:${sessionId}`
 }
 
 function getSession(instanceId: string, sessionId: string): Session | null {
@@ -47,19 +47,20 @@ export function getSessionRetry(instanceId: string, sessionId: string): SessionR
 export function markSessionIdleFadeStarted(instanceId: string, sessionId: string): void {
   const session = getSession(instanceId, sessionId)
   if (!session || session.status !== "idle" || typeof session.idleSince !== "number") return
-  const key = idleFadeKey(instanceId, sessionId, session.idleSince)
-  setIdleFadeStarts((prev) => {
-    if (prev.has(key)) return prev
+  const idleSince = session.idleSince
+  const key = idleFadeKey(instanceId, sessionId)
+  setIdleFades((prev) => {
+    if (prev.get(key) === idleSince) return prev
     const next = new Map(prev)
-    next.set(key, Date.now())
+    next.set(key, idleSince)
     return next
   })
 }
 
 export function clearSessionIdleFade(instanceId: string, sessionId: string, idleSince: number): void {
-  const key = idleFadeKey(instanceId, sessionId, idleSince)
-  setIdleFadeStarts((prev) => {
-    if (!prev.has(key)) return prev
+  const key = idleFadeKey(instanceId, sessionId)
+  setIdleFades((prev) => {
+    if (prev.get(key) !== idleSince) return prev
     const next = new Map(prev)
     next.delete(key)
     return next
@@ -68,9 +69,11 @@ export function clearSessionIdleFade(instanceId: string, sessionId: string, idle
 
 export function getSessionIdleFadeClass(instanceId: string, sessionId: string): string {
   const session = getSession(instanceId, sessionId)
-  if (!session || session.status !== "idle" || typeof session.idleSince !== "number") return ""
-  const startedAt = idleFadeStarts().get(idleFadeKey(instanceId, sessionId, session.idleSince))
-  return typeof startedAt === "number" ? "session-status-fading" : ""
+  if (!session || session.status !== "idle") return ""
+  const fadingIdleSince = idleFades().get(idleFadeKey(instanceId, sessionId))
+  if (fadingIdleSince === undefined) return ""
+  if (typeof session.idleSince === "number" && session.idleSince !== fadingIdleSince) return ""
+  return "session-status-fading"
 }
 
 export function getInstanceIdleFadeClass(instanceId: string, now = Date.now(), keepUnseenSubagentIdleStatus = false): string {
diff --git a/packages/ui/src/stores/session-tree.test.ts b/packages/ui/src/stores/session-tree.test.ts
new file mode 100644
index 00000000..e11d9a67
--- /dev/null
+++ b/packages/ui/src/stores/session-tree.test.ts
@@ -0,0 +1,180 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import type { Session } from "../types/session"
+import {
+  buildSessionThreadsFromMap,
+  collectSessionThreadIds,
+  collectVisibleSessionIds,
+  flattenVisibleSessionThreads,
+  findSessionThread,
+  getDescendantSessionsFromMap,
+  getSessionAncestorIdsFromMap,
+  getSessionRootFromMap,
+  sortSessionIdsDeepestFirst,
+} from "./session-tree"
+
+function session(id: string, parentId: string | null, updated: number): Session {
+  return { id, parentId, time: { created: updated, updated } } as Session
+}
+
+function sessionMap(definitions: Array<[string, string | null, number]>): Map<string, Session> {
+  return new Map(definitions.map(([id, parentId, updated]) => [id, session(id, parentId, updated)]))
+}
+
+describe("session tree", () => {
+  it("preserves nesting and sorts siblings by descendant activity", () => {
+    const sessions = sessionMap([
+      ["root", null, 100],
+      ["older-branch", "root", 200],
+      ["newer-branch", "root", 300],
+      ["deep-active", "older-branch", 500],
+    ])
+
+    const [root] = buildSessionThreadsFromMap(sessions, ["root"])
+    assert.equal(root.latestUpdated, 500)
+    assert.deepEqual(root.children.map((child) => child.session.id), ["older-branch", "newer-branch"])
+    assert.equal(root.children[0].children[0].session.id, "deep-active")
+    assert.equal(root.children[0].children[0].depth, 2)
+  })
+
+  it("includes the complete ancestor path for filtered descendants", () => {
+    const sessions = sessionMap([
+      ["root", null, 100],
+      ["child", "root", 200],
+      ["grandchild", "child", 300],
+      ["sibling", "root", 400],
+    ])
+
+    const [root] = buildSessionThreadsFromMap(sessions, ["root"], new Set(["grandchild"]))
+    assert.deepEqual(root.children.map((child) => child.session.id), ["child"])
+    assert.deepEqual(root.children[0].children.map((child) => child.session.id), ["grandchild"])
+    assert.equal(buildSessionThreadsFromMap(sessions, ["root", "root"]).length, 1)
+  })
+
+  it("only exposes descendants whose full parent path is expanded", () => {
+    const sessions = sessionMap([
+      ["root", null, 100],
+      ["child", "root", 200],
+      ["grandchild", "child", 300],
+    ])
+    const threads = buildSessionThreadsFromMap(sessions, ["root"])
+
+    assert.deepEqual(collectVisibleSessionIds(threads, undefined), ["root"])
+    assert.deepEqual(collectVisibleSessionIds(threads, new Set(["root"])), ["root", "child"])
+    assert.deepEqual(collectVisibleSessionIds(threads, new Set(["root", "child"])), ["root", "child", "grandchild"])
+  })
+
+  it("flattens visible nested rows in pre-order with sibling metadata", () => {
+    const sessions = sessionMap([
+      ["root", null, 100],
+      ["child", "root", 400],
+      ["grandchild", "child", 300],
+      ["sibling", "root", 200],
+      ["other-root", null, 50],
+    ])
+    const threads = buildSessionThreadsFromMap(sessions, ["root", "other-root"])
+    const expanded = new Set(["root", "child"])
+    const rows = flattenVisibleSessionThreads(threads, (id) => expanded.has(id))
+
+    assert.deepEqual(rows.map((row) => row.sessionId), ["root", "child", "grandchild", "sibling", "other-root"])
+    assert.deepEqual(rows.map((row) => row.depth), [0, 1, 2, 1, 0])
+    assert.deepEqual(rows.map((row) => row.isLastChild), [false, false, true, true, true])
+    assert.deepEqual(rows.map((row) => row.expanded), [true, true, false, false, false])
+  })
+
+  it("does not expose descendants through a collapsed ancestor", () => {
+    const sessions = sessionMap([
+      ["root", null, 100],
+      ["child", "root", 200],
+      ["grandchild", "child", 300],
+    ])
+    const threads = buildSessionThreadsFromMap(sessions, ["root"])
+    const rows = flattenVisibleSessionThreads(threads, (id) => id === "child")
+
+    assert.deepEqual(rows.map((row) => row.sessionId), ["root"])
+  })
+
+  it("matches the existing visible-id traversal for expansion sets", () => {
+    const sessions = sessionMap([
+      ["root", null, 100],
+      ["child", "root", 200],
+      ["grandchild", "child", 300],
+      ["sibling", "root", 400],
+    ])
+    const threads = buildSessionThreadsFromMap(sessions, ["root"])
+
+    for (const expanded of [new Set<string>(), new Set(["root"]), new Set(["root", "child"])]) {
+      assert.deepEqual(
+        flattenVisibleSessionThreads(threads, (id) => expanded.has(id)).map((row) => row.sessionId),
+        collectVisibleSessionIds(threads, expanded),
+      )
+    }
+  })
+
+  it("derives children from the projected filtered tree", () => {
+    const sessions = sessionMap([
+      ["root", null, 100],
+      ["child", "root", 200],
+    ])
+    const [filteredRoot] = buildSessionThreadsFromMap(sessions, ["root"], new Set())
+    const [row] = flattenVisibleSessionThreads([filteredRoot], () => true)
+
+    assert.equal(row.hasChildren, false)
+    assert.equal(row.expanded, false)
+  })
+
+  it("projects large root lists without dropping or duplicating sessions", () => {
+    const definitions: Array<[string, string | null, number]> = []
+    for (let index = 0; index < 1_000; index += 1) definitions.push([`session-${index}`, null, index])
+    const sessions = sessionMap(definitions)
+    const threads = buildSessionThreadsFromMap(sessions, definitions.map(([id]) => id))
+    const rows = flattenVisibleSessionThreads(threads, () => false)
+
+    assert.equal(rows.length, 1_000)
+    assert.equal(new Set(rows.map((row) => row.sessionId)).size, 1_000)
+  })
+
+  it("resolves roots and ancestors across arbitrary depth", () => {
+    const sessions = sessionMap([
+      ["root", null, 100],
+      ["child", "root", 200],
+      ["grandchild", "child", 300],
+    ])
+
+    assert.equal(getSessionRootFromMap(sessions, "grandchild")?.id, "root")
+    assert.deepEqual(getSessionAncestorIdsFromMap(sessions, "grandchild"), ["root", "child"])
+  })
+
+  it("terminates safely for cycles and missing parents", () => {
+    const sessions = sessionMap([
+      ["a", "b", 100],
+      ["b", "a", 200],
+      ["orphan", "missing", 300],
+    ])
+
+    assert.equal(getSessionRootFromMap(sessions, "a"), null)
+    assert.equal(getSessionRootFromMap(sessions, "orphan"), null)
+    assert.deepEqual(getSessionAncestorIdsFromMap(sessions, "a"), [])
+    assert.deepEqual(getDescendantSessionsFromMap(sessions, "a").map((item) => item.id), ["b"])
+    assert.deepEqual(buildSessionThreadsFromMap(sessions, ["a", "orphan"]), [])
+  })
+
+  it("collects an intermediate subtree and orders deletion children before parents", () => {
+    const sessions = sessionMap([
+      ["root", null, 100],
+      ["child", "root", 200],
+      ["grandchild", "child", 300],
+      ["sibling", "root", 400],
+    ])
+    const threads = buildSessionThreadsFromMap(sessions, ["root"])
+    const child = findSessionThread(threads, "child")
+
+    assert.ok(child)
+    assert.deepEqual(collectSessionThreadIds([child]), ["child", "grandchild"])
+    assert.deepEqual(
+      sortSessionIdsDeepestFirst(sessions, ["root", "child", "grandchild"]),
+      ["grandchild", "child", "root"],
+    )
+  })
+})
diff --git a/packages/ui/src/stores/session-tree.ts b/packages/ui/src/stores/session-tree.ts
new file mode 100644
index 00000000..1d1a893a
--- /dev/null
+++ b/packages/ui/src/stores/session-tree.ts
@@ -0,0 +1,196 @@
+import type { Session } from "../types/session"
+
+export type SessionThread = {
+  session: Session
+  children: SessionThread[]
+  depth: number
+  hasChildren: boolean
+  latestUpdated: number
+}
+
+export type VisibleSessionRow = {
+  sessionId: string
+  thread: SessionThread
+  depth: number
+  isLastChild: boolean
+  hasChildren: boolean
+  expanded: boolean
+}
+
+export function getSessionRootFromMap(instanceSessions: Map<string, Session>, sessionId: string): Session | null {
+  let current = instanceSessions.get(sessionId)
+  if (!current) return null
+
+  const seen = new Set<string>()
+  while (current.parentId) {
+    if (seen.has(current.id)) return null
+    seen.add(current.id)
+    const parent = instanceSessions.get(current.parentId)
+    if (!parent) return null
+    current = parent
+  }
+  return current
+}
+
+export function getSessionAncestorIdsFromMap(instanceSessions: Map<string, Session>, sessionId: string): string[] {
+  const ancestors: string[] = []
+  const seen = new Set<string>([sessionId])
+  let current = instanceSessions.get(sessionId)
+  while (current?.parentId) {
+    if (seen.has(current.parentId)) return []
+    seen.add(current.parentId)
+    const parent = instanceSessions.get(current.parentId)
+    if (!parent) return []
+    ancestors.push(parent.id)
+    current = parent
+  }
+  ancestors.reverse()
+  return ancestors
+}
+
+export function getDescendantSessionsFromMap(instanceSessions: Map<string, Session>, parentId: string): Session[] {
+  const childrenByParent = new Map<string, Session[]>()
+  for (const session of instanceSessions.values()) {
+    if (!session.parentId) continue
+    const children = childrenByParent.get(session.parentId)
+    if (children) children.push(session)
+    else childrenByParent.set(session.parentId, [session])
+  }
+
+  const descendants: Session[] = []
+  const queue = [...(childrenByParent.get(parentId) ?? [])]
+  const seen = new Set<string>([parentId])
+  while (queue.length > 0) {
+    const session = queue.shift()
+    if (!session || seen.has(session.id)) continue
+    seen.add(session.id)
+    descendants.push(session)
+    queue.push(...(childrenByParent.get(session.id) ?? []))
+  }
+  descendants.sort((a, b) => (b.time.updated ?? 0) - (a.time.updated ?? 0))
+  return descendants
+}
+
+function buildThread(
+  session: Session,
+  childrenByParent: Map<string, Session[]>,
+  depth: number,
+  ancestorIds: Set<string>,
+): SessionThread | null {
+  if (ancestorIds.has(session.id)) return null
+  const nextAncestorIds = new Set(ancestorIds)
+  nextAncestorIds.add(session.id)
+
+  const children: SessionThread[] = []
+  for (const child of childrenByParent.get(session.id) ?? []) {
+    const childThread = buildThread(child, childrenByParent, depth + 1, nextAncestorIds)
+    if (childThread) children.push(childThread)
+  }
+  children.sort((a, b) => {
+    if (b.latestUpdated !== a.latestUpdated) return b.latestUpdated - a.latestUpdated
+    return b.session.id.localeCompare(a.session.id)
+  })
+
+  let latestUpdated = session.time.updated ?? 0
+  for (const child of children) latestUpdated = Math.max(latestUpdated, child.latestUpdated)
+  return { session, children, depth, hasChildren: children.length > 0, latestUpdated }
+}
+
+export function buildSessionThreadsFromMap(
+  instanceSessions: Map<string, Session>,
+  rootIds: string[],
+  includedDescendantIds?: Set<string>,
+): SessionThread[] {
+  let includedIds: Set<string> | null = null
+  if (includedDescendantIds) {
+    includedIds = new Set(rootIds)
+    for (const sessionId of includedDescendantIds) {
+      includedIds.add(sessionId)
+      for (const ancestorId of getSessionAncestorIdsFromMap(instanceSessions, sessionId)) includedIds.add(ancestorId)
+    }
+  }
+
+  const childrenByParent = new Map<string, Session[]>()
+  for (const session of instanceSessions.values()) {
+    if (!session.parentId || (includedIds && !includedIds.has(session.id))) continue
+    const children = childrenByParent.get(session.parentId)
+    if (children) children.push(session)
+    else childrenByParent.set(session.parentId, [session])
+  }
+
+  const threads: SessionThread[] = []
+  const seenRootIds = new Set<string>()
+  for (const rootId of rootIds) {
+    if (seenRootIds.has(rootId)) continue
+    seenRootIds.add(rootId)
+    const root = instanceSessions.get(rootId)
+    if (!root || root.parentId !== null) continue
+    const thread = buildThread(root, childrenByParent, 0, new Set())
+    if (thread) threads.push(thread)
+  }
+  threads.sort((a, b) => {
+    if (b.latestUpdated !== a.latestUpdated) return b.latestUpdated - a.latestUpdated
+    const updatedDelta = (b.session.time.updated ?? 0) - (a.session.time.updated ?? 0)
+    return updatedDelta || b.session.id.localeCompare(a.session.id)
+  })
+  return threads
+}
+
+export function collectVisibleSessionIds(threads: SessionThread[], expanded: Set<string> | undefined): string[] {
+  const ids: string[] = []
+  for (const thread of threads) {
+    ids.push(thread.session.id)
+    if (expanded?.has(thread.session.id)) ids.push(...collectVisibleSessionIds(thread.children, expanded))
+  }
+  return ids
+}
+
+export function flattenVisibleSessionThreads(
+  threads: readonly SessionThread[],
+  isExpanded: (sessionId: string) => boolean,
+): VisibleSessionRow[] {
+  const rows: VisibleSessionRow[] = []
+
+  const append = (siblings: readonly SessionThread[], depth: number) => {
+    siblings.forEach((thread, index) => {
+      const hasChildren = thread.children.length > 0
+      const expanded = hasChildren && isExpanded(thread.session.id)
+      rows.push({
+        sessionId: thread.session.id,
+        thread,
+        depth,
+        isLastChild: index === siblings.length - 1,
+        hasChildren,
+        expanded,
+      })
+      if (expanded) append(thread.children, depth + 1)
+    })
+  }
+
+  append(threads, 0)
+  return rows
+}
+
+export function findSessionThread(threads: SessionThread[], sessionId: string): SessionThread | null {
+  for (const thread of threads) {
+    if (thread.session.id === sessionId) return thread
+    const child = findSessionThread(thread.children, sessionId)
+    if (child) return child
+  }
+  return null
+}
+
+export function collectSessionThreadIds(threads: SessionThread[]): string[] {
+  const ids: string[] = []
+  for (const thread of threads) {
+    ids.push(thread.session.id)
+    ids.push(...collectSessionThreadIds(thread.children))
+  }
+  return ids
+}
+
+export function sortSessionIdsDeepestFirst(instanceSessions: Map<string, Session>, sessionIds: string[]): string[] {
+  return [...sessionIds].sort(
+    (left, right) => getSessionAncestorIdsFromMap(instanceSessions, right).length - getSessionAncestorIdsFromMap(instanceSessions, left).length,
+  )
+}
diff --git a/packages/ui/src/stores/sessions.ts b/packages/ui/src/stores/sessions.ts
index a4239318..9fd27961 100644
--- a/packages/ui/src/stores/sessions.ts
+++ b/packages/ui/src/stores/sessions.ts
@@ -6,10 +6,15 @@ import {
   activeParentSessionId,
   activeSessionId,
   agents,
+  clearActiveSession,
   clearActiveParentSession,
+  clearInstanceSessionSelection,
+  clearInstanceDraftPromptValues,
   clearInstanceDraftPrompts,
   clearSessionDraftPrompt,
-  ensureSessionParentExpanded,
+  ensureSessionAncestorsExpanded,
+  ensureSessionExpanded,
+  expandedSessions,
   getActiveParentSession,
   getActiveSession,
   getChildSessions,
@@ -17,8 +22,20 @@ import {
   getSessionRoot,
   getParentSessions,
   getSessionDraftPrompt,
+  getSessionDraftPromptsForInstance,
+  getAuthoritativeDraftSessionIdsForInstance,
+  getAuthoritativelyDeletedSessionIdsForInstance,
+  getAuthoritativeSessionExpansionIdsForInstance,
+  hasAuthoritativeSessionSelection,
+  hydrateActiveSessionSelection,
+  hydrateSessionIdleMarkers,
+  hydrateSessionGenerationRecovery,
+  hydrateSessionExpansion,
+  beginSessionGenerationAdmission,
+  cancelSessionGenerationAdmissions,
   getSessionFamily,
   getSessionInfo,
+  getSessionListError,
   getSessionMessagesLoadError,
   getSessionSearchQuery,
   getSessionSearchThreads,
@@ -28,7 +45,7 @@ import {
   getVisibleSessionIds,
   isSessionBusy,
   isSessionMessagesLoading,
-  isSessionParentExpanded,
+  isSessionExpanded,
   loading,
   markSessionIdleSeen,
   markViewedSessionIdleSeen,
@@ -39,26 +56,33 @@ import {
   setActiveSession,
   setActiveSessionFromList,
   setSessionDraftPrompt,
-  setSessionParentExpanded,
+  setSessionExpanded,
   setSessionStatus,
-  toggleSessionParentExpanded,
+  toggleSessionExpanded,
   clearSessionSearch,
   getSessionHasMore,
+  hydrateSessionDraftPrompt,
   isSessionSearchLoading,
+  onSessionDraftHydrated,
   resetSessionPagination,
+  clearInstanceDeletedSessionAuthority,
+  clearInstanceSessionExpansionState,
 } from "./session-state"
 
 import { getDefaultModel } from "./session-models"
+import { handleWorktreeReady } from "./worktrees"
 import {
   createSession,
   deleteSession,
   fetchAgents,
   fetchProviders,
   fetchSessions,
+  hydrateRestoredSessionChain,
   loadMoreSessions,
   searchSessions,
   forkSession,
   loadMessages,
+  clearSessionListRequestState,
 } from "./session-api"
 import {
   abortSession,
@@ -79,6 +103,7 @@ import {
   handleQuestionAnswered,
   handleQuestionAsked,
   handleSessionCompacted,
+  handleSessionDeleted,
   handleSessionError,
   handleSessionIdle,
   handleSessionStatus,
@@ -93,6 +118,7 @@ sseManager.onMessageRemoved = handleMessageRemoved
 sseManager.onMessagePartRemoved = handleMessagePartRemoved
 sseManager.onSessionUpdate = handleSessionUpdate
 sseManager.onSessionCompacted = handleSessionCompacted
+sseManager.onSessionDeleted = handleSessionDeleted
 sseManager.onSessionError = handleSessionError
 sseManager.onSessionIdle = handleSessionIdle
 sseManager.onSessionStatus = handleSessionStatus
@@ -101,24 +127,31 @@ sseManager.onPermissionUpdated = handlePermissionUpdated
 sseManager.onPermissionReplied = handlePermissionReplied
 sseManager.onQuestionAsked = handleQuestionAsked
 sseManager.onQuestionAnswered = handleQuestionAnswered
+sseManager.onWorktreeReady = handleWorktreeReady
 
 export {
   abortSession,
   activeParentSessionId,
   activeSessionId,
   agents,
+  clearActiveSession,
   clearActiveParentSession,
+  clearInstanceSessionSelection,
+  clearInstanceDraftPromptValues,
   clearInstanceDraftPrompts,
   clearSessionDraftPrompt,
   createSession,
   deleteSession,
-  ensureSessionParentExpanded,
+  ensureSessionAncestorsExpanded,
+  ensureSessionExpanded,
+  expandedSessions,
   executeCustomCommand,
   renameSession,
   runShellCommand,
   fetchAgents,
   fetchProviders,
   fetchSessions,
+  hydrateRestoredSessionChain,
   loadMoreSessions,
   searchSessions,
   forkSession,
@@ -130,8 +163,20 @@ export {
   getDefaultModel,
   getParentSessions,
   getSessionDraftPrompt,
+  getSessionDraftPromptsForInstance,
+  getAuthoritativeDraftSessionIdsForInstance,
+  getAuthoritativelyDeletedSessionIdsForInstance,
+  getAuthoritativeSessionExpansionIdsForInstance,
+  hasAuthoritativeSessionSelection,
+  hydrateActiveSessionSelection,
+  hydrateSessionIdleMarkers,
+  hydrateSessionGenerationRecovery,
+  hydrateSessionExpansion,
+  beginSessionGenerationAdmission,
+  cancelSessionGenerationAdmissions,
   getSessionFamily,
   getSessionInfo,
+  getSessionListError,
   getSessionMessagesLoadError,
   getSessionSearchQuery,
   getSessionSearchThreads,
@@ -141,8 +186,9 @@ export {
   getVisibleSessionIds,
   isSessionBusy,
   isSessionMessagesLoading,
-  isSessionParentExpanded,
+  isSessionExpanded,
   loadMessages,
+  clearSessionListRequestState,
   loading,
   markSessionIdleSeen,
   markViewedSessionIdleSeen,
@@ -154,14 +200,18 @@ export {
   setActiveSession,
   setActiveSessionFromList,
   setSessionDraftPrompt,
-  setSessionParentExpanded,
+  setSessionExpanded,
   setSessionStatus,
-  toggleSessionParentExpanded,
+  toggleSessionExpanded,
   updateSessionAgent,
   updateSessionModel,
   clearSessionSearch,
   getSessionHasMore,
+  hydrateSessionDraftPrompt,
   isSessionSearchLoading,
+  onSessionDraftHydrated,
   resetSessionPagination,
+  clearInstanceDeletedSessionAuthority,
+  clearInstanceSessionExpansionState,
 }
 export type { SessionInfo }
diff --git a/packages/ui/src/stores/settings-screen.ts b/packages/ui/src/stores/settings-screen.ts
index 2a79e61f..f83f009a 100644
--- a/packages/ui/src/stores/settings-screen.ts
+++ b/packages/ui/src/stores/settings-screen.ts
@@ -1,19 +1,22 @@
 import { createSignal } from "solid-js"
 
 export type SettingsSectionId =
-  | "appearance"
+  | "general"
+  | "chat"
   | "notifications"
-  | "remote"
   | "speech"
+  | "remote"
   | "opencode"
-  | "config-files"
+  | "providers"
   | "sidecars"
+  | "config-files"
+  | "advanced"
   | "info"
 
 const [settingsOpen, setSettingsOpen] = createSignal(false)
-const [activeSettingsSection, setActiveSettingsSection] = createSignal<SettingsSectionId>("appearance")
+const [activeSettingsSection, setActiveSettingsSection] = createSignal<SettingsSectionId>("general")
 
-export function openSettings(section: SettingsSectionId = "appearance") {
+export function openSettings(section: SettingsSectionId = "general") {
   setActiveSettingsSection(section)
   setSettingsOpen(true)
 }
diff --git a/packages/ui/src/stores/sidecars.ts b/packages/ui/src/stores/sidecars.ts
index e5df4d10..d52a8d5f 100644
--- a/packages/ui/src/stores/sidecars.ts
+++ b/packages/ui/src/stores/sidecars.ts
@@ -4,6 +4,7 @@ import { tGlobal } from "../lib/i18n"
 import { serverEvents } from "../lib/server-events"
 import { getLogger } from "../lib/logger"
 import type { SideCar } from "../../../server/src/api-types"
+import { getAbortReason, runAbortable } from "./app-session-restore-timeout"
 
 const log = getLogger("api")
 
@@ -27,22 +28,38 @@ const [activeSidecarToken, setActiveSidecarToken] = createSignal<string | null>(
 const [sidecarsLoading, setSidecarsLoading] = createSignal(false)
 
 let loadPromise: Promise<void> | null = null
+let sidecarTabSequence = 0
 
-async function ensureSidecarsLoaded() {
-  if (loadPromise) return loadPromise
-  setSidecarsLoading(true)
-  loadPromise = serverApi.fetchSidecars()
-    .then((result) => {
+export class SidecarNotFoundError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "SidecarNotFoundError"
+  }
+}
+
+async function ensureSidecarsLoaded(options?: { propagateErrors?: boolean }): Promise<void> {
+  if (!loadPromise) {
+    setSidecarsLoading(true)
+    const pending = serverApi.fetchSidecars().then((result) => {
       setSidecars(new Map(result.sidecars.map((sidecar) => [sidecar.id, sidecar])))
     })
-    .catch((error) => {
-      log.error("Failed to load SideCars", error)
-    })
-    .finally(() => {
-      setSidecarsLoading(false)
-      loadPromise = null
-    })
-  return loadPromise
+    loadPromise = pending
+    void pending.then(
+      () => {
+        setSidecarsLoading(false)
+        if (loadPromise === pending) loadPromise = null
+      },
+      (error) => {
+        log.error("Failed to load SideCars", error)
+        setSidecarsLoading(false)
+        if (loadPromise === pending) loadPromise = null
+      },
+    )
+  }
+
+  const pending = loadPromise!
+  if (options?.propagateErrors) return pending
+  await pending.catch(() => undefined)
 }
 
 function upsertSidecar(sidecar: SideCar) {
@@ -94,18 +111,25 @@ serverEvents.on("sidecar.removed", (event) => {
   removeSidecar(event.sidecarId)
 })
 
-async function openSidecarTab(sidecarId: string) {
-  await ensureSidecarsLoaded()
+async function openSidecarTab(
+  sidecarId: string,
+  options?: { activate?: boolean; propagateLoadErrors?: boolean; signal?: AbortSignal },
+) {
+  if (options?.signal?.aborted) throw getAbortReason(options.signal)
+  await runAbortable(
+    () => ensureSidecarsLoaded({ propagateErrors: options?.propagateLoadErrors }),
+    { signal: options?.signal },
+  )
 
   const sidecar = sidecars().get(sidecarId)
   if (!sidecar) {
-    throw new Error(tGlobal("sidecars.open.notFound"))
+    throw new SidecarNotFoundError(tGlobal("sidecars.open.notFound"))
   }
   if (sidecar.status !== "running") {
     throw new Error(tGlobal("sidecars.open.notRunning"))
   }
 
-  const token = `${sidecarId}:${Date.now().toString(36)}`
+  const token = `${sidecarId}:${Date.now().toString(36)}:${(sidecarTabSequence++).toString(36)}`
   const nextTab: SideCarTabRecord = {
     token,
     sidecarId,
@@ -116,8 +140,11 @@ async function openSidecarTab(sidecarId: string) {
     shellUrl: buildSidecarShellUrl(sidecarId),
   }
 
+  if (options?.signal?.aborted) throw getAbortReason(options.signal)
   setSidecarTabs((prev) => [...prev, nextTab])
-  setActiveSidecarToken(nextTab.token)
+  if (options?.activate ?? true) {
+    setActiveSidecarToken(nextTab.token)
+  }
   return nextTab
 }
 
diff --git a/packages/ui/src/stores/speech.ts b/packages/ui/src/stores/speech.ts
index c7440bdc..45832e4c 100644
--- a/packages/ui/src/stores/speech.ts
+++ b/packages/ui/src/stores/speech.ts
@@ -5,9 +5,18 @@ import { getLogger } from "../lib/logger"
 
 const log = getLogger("api")
 
+function normalizeCapabilities(result: SpeechCapabilitiesResponse): SpeechCapabilitiesResponse {
+  const r = result as unknown as Record<string, unknown>
+  if (r.sttConfigured === undefined) r.sttConfigured = r.configured
+  if (r.ttsConfigured === undefined) r.ttsConfigured = r.configured
+  if (r.separateProviders === undefined) r.separateProviders = false
+  return r as unknown as SpeechCapabilitiesResponse
+}
+
 const [speechCapabilities, setSpeechCapabilities] = createSignal<SpeechCapabilitiesResponse | null>(null)
 const [speechCapabilitiesLoading, setSpeechCapabilitiesLoading] = createSignal(false)
 const [speechCapabilitiesError, setSpeechCapabilitiesError] = createSignal<string | null>(null)
+const [serverSupportsSeparateProviders, setServerSupportsSeparateProviders] = createSignal(false)
 
 let speechCapabilitiesPromise: Promise<SpeechCapabilitiesResponse | null> | null = null
 
@@ -20,9 +29,12 @@ async function loadSpeechCapabilities(force = false): Promise<SpeechCapabilities
   speechCapabilitiesPromise = serverApi
     .fetchSpeechCapabilities()
     .then((result) => {
-      setSpeechCapabilities(result)
+      const raw = result as unknown as Record<string, unknown>
+      setServerSupportsSeparateProviders("separateProviders" in raw)
+      const normalized = normalizeCapabilities(result)
+      setSpeechCapabilities(normalized)
       setSpeechCapabilitiesError(null)
-      return result
+      return normalized
     })
     .catch((error) => {
       log.error("Failed to load speech capabilities", error)
@@ -41,6 +53,7 @@ async function loadSpeechCapabilities(force = false): Promise<SpeechCapabilities
 function resetSpeechCapabilities(): void {
   setSpeechCapabilities(null)
   setSpeechCapabilitiesError(null)
+  setServerSupportsSeparateProviders(false)
 }
 
-export { speechCapabilities, speechCapabilitiesLoading, speechCapabilitiesError, loadSpeechCapabilities, resetSpeechCapabilities }
+export { speechCapabilities, speechCapabilitiesLoading, speechCapabilitiesError, serverSupportsSeparateProviders, loadSpeechCapabilities, resetSpeechCapabilities }
diff --git a/packages/ui/src/stores/workspace-list-reconciliation-fence.test.ts b/packages/ui/src/stores/workspace-list-reconciliation-fence.test.ts
new file mode 100644
index 00000000..563e5465
--- /dev/null
+++ b/packages/ui/src/stores/workspace-list-reconciliation-fence.test.ts
@@ -0,0 +1,49 @@
+import assert from "node:assert/strict"
+import { readFileSync } from "node:fs"
+import { describe, it } from "node:test"
+import { WorkspaceListReconciliationFence } from "./workspace-list-reconciliation-fence.ts"
+
+describe("workspace list reconciliation fence", () => {
+  it("is wired before restore gates and event early returns", () => {
+    const source = readFileSync(new URL("./instances.ts", import.meta.url), "utf8")
+    const refresh = source.slice(source.indexOf("async function refreshWorkspaceList"), source.indexOf("const initialWorkspaceLoad"))
+    assert.ok(refresh.indexOf("workspaceListReconciliationFence.allows(requestFence, workspace.id)")
+      < refresh.indexOf("restoreCreationCommitGates.deferRefreshWorkspace(workspace)"))
+    const events = source.slice(source.indexOf("function handleWorkspaceEvent"), source.indexOf("function handleWorkspaceLog"))
+    assert.ok(events.indexOf("workspaceListReconciliationFence.markMutation(workspaceId)")
+      < events.indexOf("restoreCreationCommitGates.deferWorkspace(event.workspace)"))
+    const create = source.slice(source.indexOf("async function createInstance"), source.indexOf("function normalizeInstanceFolderPath"))
+    assert.ok(create.indexOf("workspaceListReconciliationFence.markMutation(workspace.id)")
+      < create.indexOf("upsertWorkspace(committedWorkspace"))
+    const stop = source.slice(source.indexOf("function stopInstance"), source.indexOf("async function fetchLspStatus"))
+    assert.ok(stop.indexOf("workspaceListReconciliationFence.markMutation(id)") < stop.indexOf("removeInstance(id)"))
+  })
+
+  it("rejects stale list entries and absences after lifecycle mutations", () => {
+    const fence = new WorkspaceListReconciliationFence()
+    const request = fence.begin()
+    for (const id of ["created", "started", "errored", "stopped", "deleted"]) fence.markMutation(id)
+    for (const id of ["created", "started", "errored", "stopped", "deleted"]) {
+      assert.equal(fence.allows(request, id), false)
+    }
+    assert.equal(fence.allows(request, "unchanged"), true)
+  })
+
+  it("rejects an older response after a newer list request starts", () => {
+    const fence = new WorkspaceListReconciliationFence()
+    const older = fence.begin()
+    const newer = fence.begin()
+    assert.equal(fence.isCurrent(older), false)
+    assert.equal(fence.allows(older, "workspace"), false)
+    assert.equal(fence.allows(newer, "workspace"), true)
+  })
+
+  it("accepts state that changed before the request and resets after completion", () => {
+    const fence = new WorkspaceListReconciliationFence()
+    fence.markMutation("workspace")
+    const request = fence.begin()
+    assert.equal(fence.allows(request, "workspace"), true)
+    fence.complete(request)
+    assert.equal(fence.allows(fence.begin(), "workspace"), true)
+  })
+})
diff --git a/packages/ui/src/stores/workspace-list-reconciliation-fence.ts b/packages/ui/src/stores/workspace-list-reconciliation-fence.ts
new file mode 100644
index 00000000..d0759e05
--- /dev/null
+++ b/packages/ui/src/stores/workspace-list-reconciliation-fence.ts
@@ -0,0 +1,36 @@
+export interface WorkspaceListRequestFence {
+  requestRevision: number
+  mutationRevision: number
+}
+
+export class WorkspaceListReconciliationFence {
+  private requestRevision = 0
+  private mutationRevision = 0
+  private readonly workspaceRevisions = new Map<string, number>()
+
+  begin(): WorkspaceListRequestFence {
+    return {
+      requestRevision: ++this.requestRevision,
+      mutationRevision: this.mutationRevision,
+    }
+  }
+
+  markMutation(workspaceId: string): void {
+    this.workspaceRevisions.set(workspaceId, ++this.mutationRevision)
+  }
+
+  isCurrent(request: WorkspaceListRequestFence): boolean {
+    return request.requestRevision === this.requestRevision
+  }
+
+  allows(request: WorkspaceListRequestFence, workspaceId: string): boolean {
+    return this.isCurrent(request)
+      && (this.workspaceRevisions.get(workspaceId) ?? 0) <= request.mutationRevision
+  }
+
+  complete(request: WorkspaceListRequestFence): void {
+    if (!this.isCurrent(request)) return
+    this.workspaceRevisions.clear()
+    this.requestRevision += 1
+  }
+}
diff --git a/packages/ui/src/stores/worktree-ready.test.ts b/packages/ui/src/stores/worktree-ready.test.ts
new file mode 100644
index 00000000..e78456e0
--- /dev/null
+++ b/packages/ui/src/stores/worktree-ready.test.ts
@@ -0,0 +1,145 @@
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+
+import { serverApi } from "../lib/api-client.ts"
+import { ensureWorktreesLoaded, getWorktrees, handleWorktreeReady, reloadWorktrees } from "./worktrees.ts"
+
+describe("handleWorktreeReady", () => {
+  it("refreshes worktrees before synchronizing OpenCode workspaces", async () => {
+    const calls: string[] = []
+
+    await handleWorktreeReady(
+      "instance-1",
+      {
+        type: "worktree.ready",
+        directory: "/tmp/opencode/worktree/feature",
+        properties: { name: "feature", branch: "opencode/feature" },
+      },
+      async (instanceId) => {
+        calls.push(`worktrees:${instanceId}`)
+      },
+      async (instanceId) => {
+        calls.push(`workspaces:${instanceId}`)
+      },
+    )
+
+    assert.deepEqual(calls, ["worktrees:instance-1", "workspaces:instance-1"])
+  })
+
+  it("serializes overlapping ready events for the same instance", async () => {
+    const calls: string[] = []
+    let releaseFirst!: () => void
+    const firstPending = new Promise<void>((resolve) => {
+      releaseFirst = resolve
+    })
+    let refreshCount = 0
+
+    const refreshWorktrees = async () => {
+      refreshCount += 1
+      calls.push(`worktrees:${refreshCount}`)
+      if (refreshCount === 1) await firstPending
+    }
+    const refreshWorkspaces = async () => {
+      calls.push(`workspaces:${refreshCount}`)
+    }
+    const event = {
+      type: "worktree.ready" as const,
+      directory: "/tmp/opencode/worktree/feature",
+      properties: { name: "feature" },
+    }
+
+    const first = handleWorktreeReady("instance-concurrent", event, refreshWorktrees, refreshWorkspaces)
+    await Promise.resolve()
+    const second = handleWorktreeReady("instance-concurrent", event, refreshWorktrees, refreshWorkspaces)
+    await Promise.resolve()
+
+    assert.deepEqual(calls, ["worktrees:1"])
+
+    releaseFirst()
+    await Promise.all([first, second])
+
+    assert.deepEqual(calls, ["worktrees:1", "workspaces:1", "worktrees:2", "workspaces:2"])
+  })
+
+  it("continues processing after an earlier refresh rejects", async () => {
+    const event = {
+      type: "worktree.ready" as const,
+      properties: { name: "feature" },
+    }
+
+    await assert.rejects(
+      handleWorktreeReady(
+        "instance-recovery",
+        event,
+        async () => {
+          throw new Error("refresh failed")
+        },
+        async () => undefined,
+      ),
+      /refresh failed/,
+    )
+
+    const calls: string[] = []
+    await handleWorktreeReady(
+      "instance-recovery",
+      event,
+      async () => {
+        calls.push("worktrees")
+      },
+      async () => {
+        calls.push("workspaces")
+      },
+    )
+
+    assert.deepEqual(calls, ["worktrees", "workspaces"])
+  })
+
+  it("orders initial hydration before a trailing reload", async () => {
+    const instanceId = "instance-initial-reload"
+    const originalFetchWorktrees = serverApi.fetchWorktrees
+    let resolveInitial!: (value: Awaited<ReturnType<typeof serverApi.fetchWorktrees>>) => void
+    let resolveReload!: (value: Awaited<ReturnType<typeof serverApi.fetchWorktrees>>) => void
+    const initialResponse = new Promise<Awaited<ReturnType<typeof serverApi.fetchWorktrees>>>((resolve) => {
+      resolveInitial = resolve
+    })
+    const reloadResponse = new Promise<Awaited<ReturnType<typeof serverApi.fetchWorktrees>>>((resolve) => {
+      resolveReload = resolve
+    })
+    let requestCount = 0
+
+    serverApi.fetchWorktrees = async () => {
+      requestCount += 1
+      return requestCount === 1 ? initialResponse : reloadResponse
+    }
+
+    try {
+      const initial = ensureWorktreesLoaded(instanceId)
+      const reload = reloadWorktrees(instanceId)
+      await Promise.resolve()
+
+      assert.equal(requestCount, 1)
+
+      resolveInitial({
+        isGitRepo: true,
+        worktrees: [{ slug: "root", directory: "/repo", kind: "root" }],
+      })
+      await initial
+      await Promise.resolve()
+
+      assert.equal(requestCount, 2)
+
+      resolveReload({
+        isGitRepo: true,
+        worktrees: [
+          { slug: "root", directory: "/repo", kind: "root" },
+          { slug: "feature", directory: "/repo-feature", kind: "worktree" },
+        ],
+      })
+      await reload
+
+      assert.deepEqual(getWorktrees(instanceId).map((worktree) => worktree.slug), ["root", "feature"])
+    } finally {
+      serverApi.fetchWorktrees = originalFetchWorktrees
+    }
+  })
+})
diff --git a/packages/ui/src/stores/worktrees.ts b/packages/ui/src/stores/worktrees.ts
index f86b133a..be7c3860 100644
--- a/packages/ui/src/stores/worktrees.ts
+++ b/packages/ui/src/stores/worktrees.ts
@@ -1,10 +1,10 @@
 import { createSignal } from "solid-js"
 import type { WorktreeDescriptor, WorktreeMap } from "../../../server/src/api-types"
 import { serverApi } from "../lib/api-client"
-import { sessions } from "./session-state"
+import { getSessionRoot, sessions } from "./session-state"
 import { getLogger } from "../lib/logger"
-import { getCodeNomadSessionMetadata, setSessionWorktreeSlugWithClient } from "./session-metadata"
-import { getRootClient } from "./opencode-client"
+import { getCodeNomadSessionMetadata, setSessionWorktreeSlug } from "./session-metadata"
+import type { WorktreeReadyEvent } from "../lib/sse-manager"
 
 const log = getLogger("api")
 
@@ -12,10 +12,13 @@ const [worktreesByInstance, setWorktreesByInstance] = createSignal<Map<string, W
 const [worktreeMapByInstance, setWorktreeMapByInstance] = createSignal<Map<string, WorktreeMap>>(new Map())
 const [gitRepoStatusByInstance, setGitRepoStatusByInstance] = createSignal<Map<string, boolean | null>>(new Map())
 
-const worktreeLoads = new Map<string, Promise<void>>()
+const worktreeRequests = new Map<string, Promise<void>>()
+const worktreeReadyRefreshes = new Map<string, Promise<void>>()
 const mapLoads = new Map<string, Promise<void>>()
 const mapMigrations = new Map<string, Promise<void>>()
 
+type WorktreeReadyRefresh = (instanceId: string) => Promise<void>
+
 function normalizeMap(input?: WorktreeMap | null): WorktreeMap {
   if (!input || typeof input !== "object") {
     return { version: 1, defaultWorktreeSlug: "root", parentSessionWorktreeSlug: {} }
@@ -27,15 +30,11 @@ function normalizeMap(input?: WorktreeMap | null): WorktreeMap {
   }
 }
 
-async function ensureWorktreesLoaded(instanceId: string): Promise<void> {
-  if (!instanceId) return
-  if (worktreesByInstance().has(instanceId) && gitRepoStatusByInstance().has(instanceId)) return
-  const existing = worktreeLoads.get(instanceId)
-  if (existing) return existing
-
-  const task = serverApi
-    .fetchWorktrees(instanceId)
-    .then((response) => {
+async function queueWorktreeRequest(instanceId: string, initial: boolean): Promise<void> {
+  const previous = worktreeRequests.get(instanceId)
+  const task = (previous?.catch(() => undefined) ?? Promise.resolve()).then(async () => {
+    try {
+      const response = await serverApi.fetchWorktrees(instanceId)
       setWorktreesByInstance((prev) => {
         const next = new Map(prev)
         next.set(instanceId, response.worktrees ?? [])
@@ -52,9 +51,10 @@ async function ensureWorktreesLoaded(instanceId: string): Promise<void> {
       if (worktreeMapByInstance().has(instanceId)) {
         void pruneWorktreeMap(instanceId).catch(() => undefined)
       }
-    })
-    .catch((error) => {
-      log.warn("Failed to load worktrees", { instanceId, error })
+    } catch (error) {
+      log.warn(initial ? "Failed to load worktrees" : "Failed to reload worktrees", { instanceId, error })
+      if (!initial) return
+
       setWorktreesByInstance((prev) => {
         const next = new Map(prev)
         next.set(instanceId, [])
@@ -68,39 +68,64 @@ async function ensureWorktreesLoaded(instanceId: string): Promise<void> {
         next.set(instanceId, null)
         return next
       })
-    })
-    .finally(() => {
-      worktreeLoads.delete(instanceId)
-    })
+    }
+  })
 
-  worktreeLoads.set(instanceId, task)
-  return task
+  worktreeRequests.set(instanceId, task)
+  await task.finally(() => {
+    if (worktreeRequests.get(instanceId) === task) {
+      worktreeRequests.delete(instanceId)
+    }
+  })
+}
+
+async function ensureWorktreesLoaded(instanceId: string): Promise<void> {
+  if (!instanceId) return
+  if (worktreesByInstance().has(instanceId) && gitRepoStatusByInstance().has(instanceId)) return
+
+  const existing = worktreeRequests.get(instanceId)
+  if (existing) {
+    await existing
+    if (worktreesByInstance().has(instanceId) && gitRepoStatusByInstance().has(instanceId)) return
+  }
+
+  await queueWorktreeRequest(instanceId, true)
 }
 
 async function reloadWorktrees(instanceId: string): Promise<void> {
   if (!instanceId) return
-  await serverApi
-    .fetchWorktrees(instanceId)
-    .then((response) => {
-      setWorktreesByInstance((prev) => {
-        const next = new Map(prev)
-        next.set(instanceId, response.worktrees ?? [])
-        return next
-      })
+  await queueWorktreeRequest(instanceId, false)
+}
 
-      setGitRepoStatusByInstance((prev) => {
-        const next = new Map(prev)
-        next.set(instanceId, typeof response.isGitRepo === "boolean" ? response.isGitRepo : null)
-        return next
-      })
+async function handleWorktreeReady(
+  instanceId: string,
+  event: WorktreeReadyEvent,
+  refreshWorktrees: WorktreeReadyRefresh = reloadWorktrees,
+  refreshWorkspaces: WorktreeReadyRefresh = async (id) => {
+    const { reloadOpenCodeWorkspaces } = await import("./opencode-workspaces")
+    await reloadOpenCodeWorkspaces(id)
+  },
+): Promise<void> {
+  if (!instanceId) return
 
-      if (worktreeMapByInstance().has(instanceId)) {
-        void pruneWorktreeMap(instanceId).catch(() => undefined)
-      }
-    })
-    .catch((error) => {
-      log.warn("Failed to reload worktrees", { instanceId, error })
-    })
+  log.info("OpenCode worktree ready", {
+    instanceId,
+    directory: event.directory,
+    name: event.properties?.name,
+  })
+
+  const previous = worktreeReadyRefreshes.get(instanceId)
+  const task = (previous?.catch(() => undefined) ?? Promise.resolve()).then(async () => {
+    await refreshWorktrees(instanceId)
+    await refreshWorkspaces(instanceId)
+  })
+
+  worktreeReadyRefreshes.set(instanceId, task)
+  await task.finally(() => {
+    if (worktreeReadyRefreshes.get(instanceId) === task) {
+      worktreeReadyRefreshes.delete(instanceId)
+    }
+  })
 }
 
 function getGitRepoStatus(instanceId: string): boolean | null {
@@ -152,8 +177,7 @@ async function moveSessionsFromDeletedWorktree(instanceId: string, slug: string)
     .map((session) => session.id)
 
   for (const parentSessionId of parentSessionIds) {
-    const client = getRootClient(instanceId)
-    await setSessionWorktreeSlugWithClient(client, instanceId, parentSessionId, "root")
+    await setSessionWorktreeSlug(instanceId, parentSessionId, "root")
     await removeLegacyParentSessionMapping(instanceId, parentSessionId)
   }
 }
@@ -283,9 +307,7 @@ function getDefaultWorktreeSlug(instanceId: string): string {
 }
 
 function getParentSessionId(instanceId: string, sessionId: string): string {
-  const session = sessions().get(instanceId)?.get(sessionId)
-  if (!session) return sessionId
-  return session.parentId ?? session.id
+  return getSessionRoot(instanceId, sessionId)?.id ?? sessionId
 }
 
 function getWorktreeSlugForParentSession(instanceId: string, parentSessionId: string): string {
@@ -313,16 +335,14 @@ async function setWorktreeSlugForParentSession(
   await ensureWorktreeMapLoaded(instanceId)
   const current = getWorktreeMap(instanceId)
   const normalizedSlug = normalizeWorktreeSlug(instanceId, slug)
-  const client = getRootClient(instanceId)
-  await setSessionWorktreeSlugWithClient(client, instanceId, parentSessionId, normalizedSlug)
+  await setSessionWorktreeSlug(instanceId, parentSessionId, normalizedSlug)
   await removeLegacyParentSessionMapping(instanceId, parentSessionId, current)
 }
 
 async function removeParentSessionMapping(instanceId: string, parentSessionId: string): Promise<void> {
   await ensureWorktreeMapLoaded(instanceId)
   const current = getWorktreeMap(instanceId)
-  const client = getRootClient(instanceId)
-  await setSessionWorktreeSlugWithClient(client, instanceId, parentSessionId, "root")
+  await setSessionWorktreeSlug(instanceId, parentSessionId, "root")
   await removeLegacyParentSessionMapping(instanceId, parentSessionId, current)
 }
 
@@ -361,8 +381,7 @@ async function migrateLegacyWorktreeMapToSessionMetadata(instanceId: string): Pr
       }
 
       const normalizedSlug = normalizeWorktreeSlug(instanceId, legacySlug || "root")
-      const client = getRootClient(instanceId)
-      await setSessionWorktreeSlugWithClient(client, instanceId, parentSessionId, normalizedSlug)
+      await setSessionWorktreeSlug(instanceId, parentSessionId, normalizedSlug)
       await removeLegacyParentSessionMapping(instanceId, parentSessionId)
     }
   })().finally(() => {
@@ -403,6 +422,7 @@ export {
   gitRepoStatusByInstance,
   ensureWorktreesLoaded,
   reloadWorktrees,
+  handleWorktreeReady,
   reloadWorktreeMap,
   ensureWorktreeMapLoaded,
   getGitRepoStatus,
diff --git a/packages/ui/src/styles/components/config-files-settings.css b/packages/ui/src/styles/components/config-files-settings.css
index c8190d4c..929cd46a 100644
--- a/packages/ui/src/styles/components/config-files-settings.css
+++ b/packages/ui/src/styles/components/config-files-settings.css
@@ -5,6 +5,11 @@
   flex-direction: column;
 }
 
+.advanced-config-files {
+  height: 36rem;
+  min-height: 28rem;
+}
+
 .config-files-card {
   height: 100%;
   min-height: 0;
diff --git a/packages/ui/src/styles/components/folder-home.css b/packages/ui/src/styles/components/folder-home.css
index a62fcbe2..7e1256e6 100644
--- a/packages/ui/src/styles/components/folder-home.css
+++ b/packages/ui/src/styles/components/folder-home.css
@@ -46,6 +46,72 @@
   max-height: var(--folder-home-actions-height, none);
 }
 
+.folder-home-open-instance-button {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  padding: 0.125rem 0.5rem;
+  border: 1px solid var(--border-base);
+  border-radius: 9999px;
+  background-color: var(--surface-base);
+  color: var(--text-secondary);
+  font-size: 0.625rem;
+  font-weight: 500;
+  letter-spacing: 0.05em;
+  line-height: 1;
+  text-transform: uppercase;
+  transition: background-color 150ms ease, border-color 150ms ease, color 150ms ease, box-shadow 150ms ease;
+}
+
+.folder-home-open-instance-button:hover:not(:disabled),
+.folder-home-open-instance-button:focus-visible {
+  border-color: var(--accent-hover);
+  background-color: var(--accent-hover);
+  color: var(--text-on-accent);
+}
+
+.folder-home-open-instance-button:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--focus-ring-offset), 0 0 0 4px var(--focus-ring-color);
+}
+
+.folder-home-open-instance-button:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.folder-home-recent-primary-action {
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  width: 100%;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+}
+
+.folder-home-recent-primary-action:focus {
+  outline: none;
+}
+
+.folder-home-recent-primary-action:focus-visible {
+  box-shadow: inset 0 0 0 2px var(--focus-ring-color);
+}
+
+.folder-home-recent-primary-action:disabled {
+  cursor: not-allowed;
+}
+
+.folder-home-row-action:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--focus-ring-offset), 0 0 0 4px var(--focus-ring-color);
+}
+
+.folder-home-recent-item.folder-home-recent-item-action-active {
+  background-color: transparent !important;
+  box-shadow: none !important;
+}
+
 @media (min-width: 1024px) {
   .folder-home-main {
     display: grid;
diff --git a/packages/ui/src/styles/components/provider-auth.css b/packages/ui/src/styles/components/provider-auth.css
index 1acc258c..3132b842 100644
--- a/packages/ui/src/styles/components/provider-auth.css
+++ b/packages/ui/src/styles/components/provider-auth.css
@@ -12,6 +12,19 @@
   border-radius: 0;
 }
 
+.providers-manager-embedded {
+  position: static;
+  transform: none;
+  width: 100%;
+  max-height: none;
+  border: 1px solid var(--border-base);
+  background: var(--surface-base);
+}
+
+.providers-manager-embedded .providers-manager-body {
+  overflow: visible;
+}
+
 .providers-manager-header {
   display: flex;
   align-items: flex-start;
@@ -338,6 +351,12 @@
     height: 100dvh;
   }
 
+  .providers-manager-embedded {
+    width: 100%;
+    max-height: none;
+    height: auto;
+  }
+
   .providers-connect-bar,
   .providers-panel-header {
     grid-template-columns: 1fr;
diff --git a/packages/ui/src/styles/components/settings-screen.css b/packages/ui/src/styles/components/settings-screen.css
index c65f4ebf..466fd32f 100644
--- a/packages/ui/src/styles/components/settings-screen.css
+++ b/packages/ui/src/styles/components/settings-screen.css
@@ -41,6 +41,8 @@
   display: flex;
   flex-direction: column;
   gap: 1rem;
+  min-height: 0;
+  overflow: hidden;
   padding: 1.25rem;
   background:
     linear-gradient(180deg, color-mix(in oklab, var(--surface-secondary) 92%, var(--accent-primary) 8%), var(--surface-secondary));
@@ -94,6 +96,9 @@
   display: flex;
   flex-direction: column;
   gap: 0.35rem;
+  min-height: 0;
+  overflow-x: hidden;
+  overflow-y: auto;
 }
 
 .settings-nav-button {
@@ -112,7 +117,7 @@
 
 .settings-nav-button:focus-visible {
   outline: 2px solid var(--accent-primary);
-  outline-offset: 2px;
+  outline-offset: -2px;
 }
 
 .settings-nav-button:hover {
@@ -295,6 +300,18 @@
   color: var(--text-muted);
 }
 
+.settings-card-section-header {
+  margin-top: 0.75rem;
+  padding-bottom: 0.375rem;
+  border-bottom: 1px solid var(--border-base);
+}
+
+.settings-card-section-title {
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-semibold);
+  color: var(--text-secondary);
+}
+
 .settings-card-message {
   padding: 1rem;
   border: 1px dashed var(--border-base);
@@ -539,9 +556,6 @@
 .settings-expansion-table {
   margin-bottom: 1.25rem;
   border: 1px solid var(--border-base);
-  border-radius: 0;
-  background: var(--surface-base);
-  overflow: hidden;
 }
 
 .settings-expansion-table-header,
diff --git a/packages/ui/src/styles/markdown.css b/packages/ui/src/styles/markdown.css
index 5e95c471..40a488aa 100644
--- a/packages/ui/src/styles/markdown.css
+++ b/packages/ui/src/styles/markdown.css
@@ -242,6 +242,15 @@
     border-bottom: 1px solid var(--border-base);
   }
 
+  .code-block-actions {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-xs);
+    flex: 0 0 auto;
+    margin-inline-start: auto;
+    margin-inline-end: var(--space-sm);
+  }
+
   .code-block-language {
     font-family: var(--message-part-header-font-family);
     color: var(--text-primary);
@@ -252,7 +261,8 @@
     line-height: var(--message-part-header-title-line-height);
   }
 
-  .code-block-copy {
+  .code-block-copy,
+  .code-block-wrap {
     display: inline-flex;
     align-items: center;
     justify-content: center;
@@ -262,28 +272,30 @@
     padding: 0;
     background-color: transparent;
     border: none;
-    border-radius: 0.25rem;
+    border-radius: 0;
     cursor: pointer;
     color: var(--text-secondary);
     flex: 0 0 auto;
     transition:
       background-color 150ms ease,
       color 150ms ease;
-    margin-inline-start: auto;
-    margin-inline-end: var(--space-sm);
   }
 
-  .code-block-copy:hover {
+  .code-block-copy:hover,
+  .code-block-wrap:hover,
+  .code-block-wrap.active {
     background-color: transparent;
     color: var(--text-primary);
   }
 
-  .code-block-copy .copy-icon {
+  .code-block-copy .copy-icon,
+  .code-block-wrap .wrap-icon {
     width: 0.875rem;
     height: 0.875rem;
   }
 
-  .code-block-copy .copy-text {
+  .code-block-copy .copy-text,
+  .code-block-wrap .wrap-text {
     position: absolute;
     width: 1px;
     height: 1px;
@@ -311,4 +323,14 @@
     background: transparent !important;
     padding: 0 !important;
   }
+
+  .markdown-code-block[data-wrap-lines="true"] pre,
+  .markdown-code-block[data-wrap-lines="true"] code,
+  .markdown-code-block[data-wrap-lines="true"] pre.shiki,
+  .markdown-code-block[data-wrap-lines="true"] pre.shiki code,
+  .markdown-code-block[data-wrap-lines="true"] .shiki {
+    white-space: pre-wrap !important;
+    word-break: break-word;
+    overflow-wrap: anywhere;
+  }
 }
diff --git a/packages/ui/src/styles/messaging/delete-overlays.css b/packages/ui/src/styles/messaging/delete-overlays.css
index 344c8a1e..a5fb8c9f 100644
--- a/packages/ui/src/styles/messaging/delete-overlays.css
+++ b/packages/ui/src/styles/messaging/delete-overlays.css
@@ -26,10 +26,13 @@
 .delete-hover-scope[data-delete-part-hover="true"]::before {
   content: "";
   position: absolute;
-  inset: -2px;
+  inset: -4px;
   background: var(--status-error-bg);
   border-radius: 0;
   pointer-events: none;
   /* Overlay must sit above the part card background. */
   z-index: 10;
 }
+.message-reasoning-card[data-delete-part-hover="true"]::before {
+  inset: 0;
+}
diff --git a/packages/ui/src/styles/messaging/message-base.css b/packages/ui/src/styles/messaging/message-base.css
index 74611cc8..986df61c 100644
--- a/packages/ui/src/styles/messaging/message-base.css
+++ b/packages/ui/src/styles/messaging/message-base.css
@@ -214,6 +214,15 @@
   @apply flex flex-wrap items-center gap-1 text-[10px] text-[var(--text-muted)];
 }
 
+.message-step-usage-toggle {
+  @apply flex min-w-0 items-center gap-1 text-left;
+}
+
+.message-step-usage-disclosure {
+  @apply shrink-0 text-[9px];
+  color: var(--text-muted);
+}
+
 .message-step-usage-chip {
   @apply inline-flex items-center rounded-full border border-[var(--border-base)] px-2 py-0.5 text-[10px];
   color: var(--text-primary);
diff --git a/packages/ui/src/styles/panels/empty-loading.css b/packages/ui/src/styles/panels/empty-loading.css
index c558262d..dd4f6e7a 100644
--- a/packages/ui/src/styles/panels/empty-loading.css
+++ b/packages/ui/src/styles/panels/empty-loading.css
@@ -64,33 +64,3 @@
   border-top-color: var(--accent-primary);
   animation: spin 1s linear infinite;
 }
-
-.message-load-error-state {
-  @apply flex-1 flex items-center justify-center p-12;
-}
-
-.message-load-error-card {
-  @apply max-w-md rounded-xl border p-6 text-center shadow-sm;
-  background: var(--surface-secondary);
-  border-color: var(--border-base);
-}
-
-.message-load-error-card h3 {
-  @apply text-base font-semibold;
-  color: var(--text-primary);
-}
-
-.message-load-error-card p {
-  @apply mt-3 text-sm leading-6 break-words;
-  color: var(--text-muted);
-}
-
-.message-load-error-retry {
-  @apply mt-5 rounded-md px-4 py-2 text-sm font-medium transition-colors;
-  background: var(--accent-primary);
-  color: var(--text-on-accent);
-}
-
-.message-load-error-retry:hover {
-  background: var(--accent-hover);
-}
diff --git a/packages/ui/src/styles/panels/right-panel.css b/packages/ui/src/styles/panels/right-panel.css
index 14bd0d36..1d0bb460 100644
--- a/packages/ui/src/styles/panels/right-panel.css
+++ b/packages/ui/src/styles/panels/right-panel.css
@@ -38,6 +38,7 @@
 .right-panel-tab {
   @apply inline-flex items-center gap-2 px-4 py-2 text-xs font-medium transition-all duration-150 relative;
   font-family: var(--font-family-sans);
+  cursor: grab;
   outline: none;
   border: 1px solid transparent;
   border-bottom: none;
@@ -46,6 +47,14 @@
   z-index: 1;
 }
 
+.right-panel-tab-draggable {
+  display: inline-flex;
+}
+
+.right-panel-tab-draggable-active {
+  opacity: 0.75;
+}
+
 .right-panel-tab:focus-visible {
   @apply ring-2 ring-offset-1;
   ring-color: var(--accent-primary);
@@ -768,6 +777,99 @@
   min-height: 0;
 }
 
+.right-panel-section-draggable-active {
+  opacity: 0.75;
+}
+
+.right-panel-customization-popover {
+  position: absolute;
+  top: 2.75rem;
+  inset-inline-start: 0.5rem;
+  z-index: 20;
+  width: min(18rem, calc(100% - 1rem));
+  border: 1px solid var(--border-base);
+  background-color: var(--surface-secondary);
+  box-shadow: var(--popover-shadow);
+  padding: 0.75rem;
+}
+
+.right-panel-customization-header {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 0.75rem;
+  margin-bottom: 0.75rem;
+}
+
+.right-panel-customization-grid {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 0.5rem;
+}
+
+.right-panel-customization-group {
+  min-width: 0;
+  border: 1px solid var(--border-base);
+  background-color: var(--surface-primary);
+  padding: 0.5rem;
+}
+
+.right-panel-customization-group-title {
+  color: var(--text-secondary);
+  font-size: 0.75rem;
+  font-weight: 600;
+  margin-bottom: 0.35rem;
+}
+
+.right-panel-customization-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  padding: 0.25rem 0;
+}
+
+.right-panel-customization-label {
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  color: var(--text-primary);
+  font-size: 0.75rem;
+}
+
+.right-panel-customization-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid var(--border-base);
+  background-color: transparent;
+  color: var(--text-secondary);
+  font-size: 0.75rem;
+  font-weight: 500;
+  line-height: 1rem;
+  padding: 0.25rem 0.5rem;
+  transition: color 150ms, background-color 150ms;
+}
+
+.right-panel-customization-button:hover:not(:disabled) {
+  color: var(--text-primary);
+  background-color: var(--surface-hover);
+}
+
+.right-panel-customization-button:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--focus-ring-offset), 0 0 0 4px var(--focus-ring-color);
+}
+
+.right-panel-customization-hint {
+  margin-top: 0.5rem;
+  color: var(--text-tertiary);
+  font-size: 0.6875rem;
+  line-height: 1rem;
+}
+
 /* Section info tooltip */
 .section-info-trigger {
   @apply inline-flex items-center justify-center p-0.5 rounded transition-all duration-150;
diff --git a/packages/ui/src/styles/panels/session-layout.css b/packages/ui/src/styles/panels/session-layout.css
index c6223f98..53530eba 100644
--- a/packages/ui/src/styles/panels/session-layout.css
+++ b/packages/ui/src/styles/panels/session-layout.css
@@ -254,13 +254,19 @@ session-sidebar-controls .selector-trigger-primary {
 
 .session-list {
   @apply flex-1;
+  overflow-anchor: none;
+  overscroll-behavior-y: contain;
 }
 
 .session-list-item {
-  @apply border-b last:border-b-0;
+  @apply border-b;
   border-color: var(--border-base);
 }
 
+.session-list-item-last {
+  border-bottom: 0;
+}
+
 .session-item-base {
   @apply w-full flex flex-col gap-1 px-3 py-2.5 text-start transition-colors outline-none;
   font-family: var(--font-family-sans);
@@ -268,36 +274,36 @@ session-sidebar-controls .selector-trigger-primary {
 }
 
 
-.session-item-base.session-item-child {
-  padding-inline-start: 2.25rem;
+.session-item-base.session-item-nested {
+  padding-inline-start: var(--session-indent);
   position: relative;
 }
 
-.session-item-base.session-item-child::before {
+.session-item-base.session-item-nested::before {
   content: "";
   position: absolute;
   top: 0;
   bottom: 0;
-  inset-inline-start: 1.125rem;
+  inset-inline-start: var(--session-connector-offset);
   width: 1px;
   background-color: var(--text-secondary);
-  opacity: 0.95;
+  opacity: 0.65;
   pointer-events: none;
 }
 
-.session-item-base.session-item-child.session-item-child-last::before {
+.session-item-base.session-item-nested.session-item-child-last::before {
   bottom: 50%;
 }
 
-.session-item-base.session-item-child::after {
+.session-item-base.session-item-nested::after {
   content: "";
   position: absolute;
   top: 50%;
-  inset-inline-start: 1.125rem;
+  inset-inline-start: var(--session-connector-offset);
   width: 0.875rem;
   height: 1px;
   background-color: var(--text-secondary);
-  opacity: 0.95;
+  opacity: 0.65;
   transform: translateY(-0.5px);
   pointer-events: none;
 }
@@ -459,7 +465,8 @@ session-sidebar-controls .selector-trigger-primary {
 .status-indicator.session-status.session-working,
 .status-indicator.session-status.session-retrying,
 .status-indicator.session-status.session-compacting,
-.status-indicator.session-status.session-idle {
+.status-indicator.session-status.session-idle,
+.status-indicator.session-status.session-interrupted {
   font-weight: var(--font-weight-medium);
 }
 
@@ -483,6 +490,11 @@ session-sidebar-controls .selector-trigger-primary {
   --session-status-dot: var(--session-status-idle-fg);
 }
 
+.status-indicator.session-status.session-interrupted {
+  color: var(--status-warning);
+  --session-status-dot: var(--status-warning);
+}
+
 .status-indicator.session-status.session-idle.session-status-fading {
   animation: session-status-fade-out 5s ease-out forwards;
 }
@@ -517,6 +529,10 @@ session-sidebar-controls .selector-trigger-primary {
   background-color: var(--session-status-idle-bg);
 }
 
+.status-indicator.session-status.session-interrupted.session-status-list {
+  background-color: color-mix(in srgb, var(--status-warning) 12%, transparent);
+}
+
 .status-indicator.session-status.session-permission.session-status-list {
   background-color: var(--session-status-permission-bg);
 }
diff --git a/packages/ui/src/types/global.d.ts b/packages/ui/src/types/global.d.ts
index 0146cfe8..e4c3a6ab 100644
--- a/packages/ui/src/types/global.d.ts
+++ b/packages/ui/src/types/global.d.ts
@@ -22,6 +22,12 @@ declare global {
     path?: string | null
   }
 
+  interface ElectronClientStateLoadResult {
+    isPrimary: boolean
+    restoreEnabled: boolean
+    snapshot: unknown | null
+  }
+
   interface ElectronAPI {
     onCliStatus?: (callback: (data: unknown) => void) => () => void
     onCliError?: (callback: (data: unknown) => void) => () => void
@@ -32,6 +38,11 @@ declare global {
     getPathForFile?: (file: File) => string | null
     requestMicrophoneAccess?: () => Promise<{ granted: boolean }>
     setWakeLock?: (enabled: boolean) => Promise<{ enabled: boolean }>
+    claimClientStateAccess?: (accessToken: string) => Promise<boolean>
+    loadClientState?: (accessToken: string) => Promise<ElectronClientStateLoadResult>
+    saveClientState?: (accessToken: string, snapshot: unknown) => Promise<boolean>
+    setClientStateRestoreEnabled?: (accessToken: string, enabled: boolean) => Promise<boolean>
+    clearClientState?: (accessToken: string) => Promise<boolean>
 
     showNotification?: (payload: { title: string; body: string }) => Promise<{ ok: boolean; reason?: string }>
     openRemoteWindow?: (payload: {
@@ -66,9 +77,10 @@ declare global {
   interface Window {
       __CODENOMAD_API_BASE__?: string
       __CODENOMAD_EVENTS_URL__?: string
-      __CODENOMAD_RUNTIME_HOST__?: "electron" | "tauri" | "web"
-      __CODENOMAD_WINDOW_CONTEXT__?: "local" | "remote"
-      electronAPI?: ElectronAPI
+       __CODENOMAD_RUNTIME_HOST__?: "electron" | "tauri" | "web"
+       __CODENOMAD_WINDOW_CONTEXT__?: "local" | "remote"
+       __CODENOMAD_FLUSH_CLIENT_STATE_BEFORE_NATIVE_SHUTDOWN__?: () => Promise<void>
+       electronAPI?: ElectronAPI
       __TAURI__?: TauriBridge
       codenomadLogger?: LoggerControls
    }
diff --git a/packages/ui/src/types/session.ts b/packages/ui/src/types/session.ts
index e8e29ac3..8009900d 100644
--- a/packages/ui/src/types/session.ts
+++ b/packages/ui/src/types/session.ts
@@ -5,6 +5,7 @@ import type {
   Model as SDKModel,
   SessionStatus as SDKSessionStatus,
 } from "@opencode-ai/sdk/v2"
+import type { GenerationRecoveryState } from "../stores/session-generation-recovery"
 
 // Export SDK types for external use
 export type { 
@@ -76,6 +77,9 @@ export interface Session
   status: SessionStatus // Single source of truth for session status
   retry?: SessionRetryState | null // Retry metadata for transient backoff states
   idleSince?: number | null // Timestamp set when work finished but the session has not been viewed yet
+  generationRecovery?: GenerationRecoveryState | null // Local recovery state for work interrupted across restarts
+  runtimeStatusKnown?: boolean // Whether idle/working came from an authoritative runtime response
+  generationAdmissionToken?: number // Guards recovery state while a new input is being admitted
   metadata?: Record<string, unknown> // Session metadata persisted by OpenCode
 }
 
@@ -95,6 +99,8 @@ export function createClientSession(
     model,
     status,
     idleSince: null,
+    generationRecovery: null,
+    runtimeStatusKnown: false,
   }
 }